Campo extra en el checkout de Shopify con una checkout UI extension
En la práctica/ 10 min de lectura
Crea una checkout UI extension con un campo extra, guarda el valor en un metafield del carrito que se copia al pedido y mira qué targets exigen Shopify Plus.
- Checkout
- Apps de Shopify
- Shopify Plus
En este artículo (9)
Para agregar un campo extra al checkout de Shopify, crea una checkout UI extension con Shopify CLI, dibuja el campo con los componentes de Shopify y guarda lo que escriba el cliente en un metafield del carrito, que se copia al pedido. En los pasos de información, envío y pago, esto exige Shopify Plus.
Aquí tienes el código completo de un campo de referencia de compra, la tabla de targets con el plan que pide cada uno y el cambio que toca hacer si hoy guardas el dato con attributes. No lo probamos en una tienda: validamos el código y la mutación de GraphQL con las herramientas de Shopify.
Qué es una checkout UI extension
Una checkout UI extension es un programa pequeño, escrito con Preact, que Shopify ejecuta dentro del checkout en un punto fijo llamado target. Se declara en un archivo shopify.extension.toml, se dibuja con componentes web de Shopify (s-text-field, s-banner, s-checkbox) y lee o cambia el checkout a través del objeto global shopify. No editas el HTML del checkout: agregas una pieza en un lugar que Shopify ya expone.
Para un campo hacen falta tres cosas: un target donde mostrarlo, un componente que recoja el texto y un sitio donde guardar el valor para que llegue al pedido. Las tres están en el tutorial oficial y en su repositorio de ejemplo, que usan un campo de instrucciones de entrega; aquí hacemos una referencia de compra y añadimos lo que el tutorial deja fuera.
Desliza la figura para verla completa
Crear la extensión con Shopify CLI
El tutorial pide Shopify CLI 3.85.1 o superior y, dentro de tu app, este comando:
shopify app generate extension --template checkout_ui --name po-reference
shopify app generate extensioncrea una extensión dentro de la app donde estés parado.--template checkout_uielige la plantilla de checkout UI, que sigue la versión de API vigente.--name po-referencees el nombre de la carpeta y de la extensión.
El CLI crea shopify.extension.toml, src/Checkout.jsx, una carpeta locales y un package.json. Con shopify app dev y la tecla p abres la vista previa; si cambias el .toml, reinicia el comando.
Este es el shopify.extension.toml de nuestro campo. El CLI genera el uid y la versión de API (la documentación marca 2026-10 como la más reciente a 12 de noviembre de 2026); deja la que escriba el CLI:
api_version = "2026-10"
[[extensions]]
name = "po-reference"
handle = "po-reference"
type = "ui_extension"
[[extensions.targeting]]
module = "./src/Checkout.jsx"
target = "purchase.checkout.contact.render-after"
[[extensions.targeting.metafields]]
namespace = "my_app"
key = "po_reference"
api_versionfija la versión de las APIs que recibe la extensión.[[extensions]]da nombre,handle(que no cambia tras desplegar) y tipoui_extension.[[extensions.targeting]]enlaza el archivo con el target. Aquí el campo sale justo después del bloque de contacto, en el paso de información.[[extensions.targeting.metafields]]pide el metafieldmy_app.po_referencepara poder leerlo en la extensión. Cambiamy_apppor un namespace tuyo.
Elegir dónde aparece el campo en el checkout
Hay dos familias de targets. Los estáticos se pintan en un lugar fijo, como después de la lista de métodos de envío. Los de bloque (purchase.checkout.block.render) se pintan donde el comerciante los coloque. En ambos casos la extensión no se muestra hasta que el comerciante agrega el bloque de la app en el editor (en el admin en inglés: Settings > Checkout > Customize checkout > Add app block), según la guía de pruebas. La lista completa está en la referencia de targets.
Pon el campo cerca del paso al que pertenece: una referencia de compra con el contacto, unas instrucciones de entrega con el envío (purchase.checkout.shipping-option-list.render-after). Dos avisos de la guía de UX para campos y del tutorial: los targets de envío no se muestran con productos solo digitales, y shipping-option-list.render-after se pinta una vez por tipo de compra (única y suscripción), así que el ejemplo oficial devuelve null salvo en oneTimePurchase para no escribir el metafield dos veces.
Desliza la figura para verla completa
El campo con los componentes de Shopify
Este es src/Checkout.jsx. Lo validamos con el validador de la skill de Shopify para extensiones de checkout, en el target purchase.checkout.contact.render-after:
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';
const NAMESPACE = 'my_app';
const KEY = 'po_reference';
export default function extension() {
render(<Extension />, document.body);
}
function Extension() {
const {appMetafields, applyMetafieldChange, instructions, i18n} = shopify;
// The value saved earlier in this checkout, so the field survives a reload.
const saved = appMetafields.value.find(
(entry) =>
entry.target.type === 'cart' &&
entry.metafield.namespace === NAMESPACE &&
entry.metafield.key === KEY,
);
const [value, setValue] = useState(String(saved?.metafield.value ?? ''));
const [failed, setFailed] = useState(false);
// Accelerated checkout (Apple Pay, Google Pay) can turn this off.
if (!instructions.value.metafields.canSetCartMetafields) {
return null;
}
async function save() {
const text = value.trim();
const result = await applyMetafieldChange(
text === ''
? {type: 'removeCartMetafield', namespace: NAMESPACE, key: KEY}
: {
type: 'updateCartMetafield',
metafield: {
namespace: NAMESPACE,
key: KEY,
type: 'single_line_text_field',
value: text,
},
},
);
setFailed(result.type === 'error');
}
function updateValue(event) {
setValue(event.currentTarget.value);
}
return (
<s-text-field
label={i18n.translate('poLabel')}
value={value}
error={failed ? i18n.translate('poError') : undefined}
onInput={updateValue}
onBlur={save}
/>
);
}
- Las tres primeras líneas traen Preact y los componentes
s-*, que están registrados globalmente. NAMESPACEyKEYdeben ser idénticos a los del.tomly a la definición del pedido.extension()es lo que Shopify ejecuta; solo monta el componente.- Del objeto
shopifysalenappMetafields(lectura),applyMetafieldChange(escritura),instructions(qué está permitido) ei18n(textos traducidos). savedbusca el metafield de carrito para precargar el campo si el cliente vuelve a este paso.- Si
canSetCartMetafieldses falso, la extensión no se pinta. Shopify avisa de que con Apple Pay o Google Pay el cambio puede fallar. saveguarda conupdateCartMetafieldo, si el cliente vació el campo, borra conremoveCartMetafield. Corre enonBlur, no en cada tecla: la guía de rendimiento avisa de que demasiados cambios limitan la extensión.- Si
result.typeeserror, el campo muestra nuestro texto: elmessagedel error no está localizado y Shopify pide no enseñárselo al cliente. updateValuees una función con nombre porque el validador rechazó la flecha dentro del JSX.- El
s-text-fieldrecibe etiqueta, valor, error y los dos eventos. Los textos viven enlocales/en.default.jsony un archivo por idioma.
Guardar el valor en el pedido
El valor se guarda como metafield del carrito con applyMetafieldChange. Según la referencia de la API, ese metafield se copia a un metafield del pedido al crearse el pedido, siempre que exista una definición de metafield de pedido con el mismo namespace y key y con la capacidad cart to order copyable activada. Sin esa definición, el valor se queda en el carrito y no llega al pedido.
Crea la definición en el admin, texto de una línea, con la opción Copy values from cart metafields, como indica el tutorial. O con la API, usando la capacidad cartToOrderCopyable; esta mutación la validamos contra el esquema de Admin GraphQL:
mutation {
metafieldDefinitionCreate(
definition: {
name: "PO reference"
namespace: "my_app"
key: "po_reference"
type: "single_line_text_field"
ownerType: ORDER
capabilities: { cartToOrderCopyable: { enabled: true } }
}
) {
createdDefinition { id namespace key }
userErrors { field message code }
}
}
namespaceykeyrepiten los de la extensión; si difieren una letra, no hay copia.ownerType: ORDERdefine el metafield sobre pedidos, no sobre carritos.capabilitiesactivacartToOrderCopyable, la que copia el valor del carrito.- Siempre revisa
userErrors: Shopify devuelve ahí los fallos de validación.
La guía de migración añade que la app necesita el scope write_orders para que los metafields lleguen al pedido; el tutorial no lo menciona, así que confírmalo en tu app. Cuando entre un pedido de prueba, el valor aparece en la sección Metafields de su página de detalle.
Si hoy guardas el dato con applyAttributeChange, ojo: la referencia de la Attributes API lo marca como obsoleto y dice que uses metafields del carrito.
Desliza la figura para verla completa
Qué requiere Plus y qué no
La regla de Shopify: las extensiones que se muestran en los pasos de información, envío y pago solo están disponibles en tiendas con Shopify Plus. Según la página de tecnologías para personalizar el checkout, las extensiones de Thank you y Order status están disponibles en todos los planes excepto Shopify Starter. Ese "excepto Starter" corrige lo que se suele decir ("todos los planes").
| Dónde se muestra | Target de ejemplo | Plan |
|---|---|---|
| Paso de información | purchase.checkout.contact.render-after | Shopify Plus |
| Paso de envío | purchase.checkout.shipping-option-list.render-after | Shopify Plus |
| Paso de pago | purchase.checkout.payment-method-list.render-after | Shopify Plus |
| Página Thank you | purchase.thank-you.block.render | Todos menos Starter; metafields de solo lectura |
La página de gracias no sirve para este campo: el pedido ya existe y sus targets pueden leer metafields, no escribirlos. Sin Plus, el sitio para pedir el dato es el carrito del tema: un input con name="attributes[referencia]" dentro del formulario del carrito crea un atributo, según la documentación de Liquid. Comprueba con un pedido de prueba dónde lo ves en el admin.
Si lo que quieres es cambiar precios o validar el carrito en el servidor, eso es terreno de Functions: mira cómo migrar Shopify Scripts a Functions para descuentos.
Errores comunes
- No agregar el bloque en el editor. La extensión desplegada no se ve hasta que el comerciante la añade en el editor de checkout.
- Olvidar la definición del pedido, o cambiar una letra al namespace o la key. El metafield se queda en el carrito y el pedido llega sin el valor.
- Seguir usando
applyAttributeChange. Está marcado como obsoleto; usa metafields del carrito. - Guardar en cada tecla. Demasiados cambios pueden limitar la extensión; guarda al salir del campo o con una espera corta.
- No contemplar Apple Pay y Google Pay. Comprueba
canSetCartMetafieldsy maneja elerror; en pago acelerado el cambio puede fallar. - Usar un target de envío en un carrito digital. No se muestra; para un dato que aplica a todos los pedidos, usa el target de contacto.
Preguntas frecuentes
¿Puedo hacerlo sin Shopify Plus?
No dentro del checkout: información, envío y pago son solo para Plus. Thank you y Order status admiten extensiones en todos los planes menos Starter, pero con metafields de solo lectura. Sin Plus, pide el dato en el carrito del tema con un atributo.
¿Cómo hago el campo obligatorio?
Con useBuyerJourneyIntercept de la Buyer Journey API, que puede bloquear el avance y mostrar un error bajo un campo. Requiere la capacidad block_progress en la extensión, y el comerciante debe permitirla en los ajustes de comportamiento del checkout; si no, canBlockProgress llega en falso.
¿Dónde veo lo que escribió el cliente?
En la página de detalle del pedido, en la sección Metafields, siempre que la definición del pedido tenga activa la copia desde el carrito. Haz un pedido de prueba tras cada cambio de namespace o key.
¿Por qué un metafield y no un atributo?
Porque applyAttributeChange está marcado como obsoleto en la referencia de la API, con la indicación de usar metafields del carrito, y porque el metafield tiene tipo y una definición que controlas en el admin.
Checklist
- La tienda está en Shopify Plus si el campo va en información, envío o pago.
- La extensión se creó con
shopify app generate extension --template checkout_ui. - El target está en el paso correcto y la extensión maneja el carrito solo digital.
NAMESPACE,KEYy el.tomlcoinciden con la definición del pedido.- La definición del pedido tiene la copia desde el carrito y la app tiene
write_orders. - El código comprueba
canSetCartMetafieldsy guarda al salir del campo. - El comerciante agregó el bloque de la app en el editor de checkout.
- Un pedido de prueba muestra el valor en Metafields.
Con un metafield de carrito y su definición en el pedido, el campo llega a donde lo necesitas. Si la app que aloja la extensión también tiene pantallas en el admin, revisa Polaris 2 release candidate para apps de Shopify.
¿Viste esto en Instagram? Comenta CAMPO en el Reel y te mando la guía.
Escrito por

Publicado el 12 de noviembre de 2026 · actualizado el 18 de noviembre de 2026