Saltar al contenido

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)
  1. Qué es una checkout UI extension
  2. Crear la extensión con Shopify CLI
  3. Elegir dónde aparece el campo en el checkout
  4. El campo con los componentes de Shopify
  5. Guardar el valor en el pedido
  6. Qué requiere Plus y qué no
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

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.

dónde puede ir el campo: tres pasos del checkoutinformaciónPO referencecampo extracontact.render-afterenvíoPO referencecampo extrashipping-option-listpagoPO referencecampo extrapayment-method-listlos tres pasos del checkout: solo Shopify PlusThank you y Order status: todos los planes menos Starter, metafields de solo lecturael campo vive en un paso del checkouttargets según la documentación de Shopify, API 2026-10

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
  1. shopify app generate extension crea una extensión dentro de la app donde estés parado.
  2. --template checkout_ui elige la plantilla de checkout UI, que sigue la versión de API vigente.
  3. --name po-reference es 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"
  1. api_version fija la versión de las APIs que recibe la extensión.
  2. [[extensions]] da nombre, handle (que no cambia tras desplegar) y tipo ui_extension.
  3. [[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.
  4. [[extensions.targeting.metafields]] pide el metafield my_app.po_reference para poder leerlo en la extensión. Cambia my_app por 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.

targets del checkout y el plan que exige cada unotargetpasoplanpurchase.checkout.contact.render-afterinformaciónPluspurchase.checkout.shipping-option-list.render-afterenvíoPluspurchase.checkout.payment-method-list.render-afterpagoPluspurchase.checkout.block.renderen el editorPluspurchase.thank-you.block.renderThank youtodos menos Starteren Thank you el metafield es de solo lectura: ahí no se guarda el campoinformación, envío y pago: solo Shopify Plusfuente: shopify.dev, targets y tecnologías de checkout, API 2026-10

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}
    />
  );
}
  1. Las tres primeras líneas traen Preact y los componentes s-*, que están registrados globalmente.
  2. NAMESPACE y KEY deben ser idénticos a los del .toml y a la definición del pedido.
  3. extension() es lo que Shopify ejecuta; solo monta el componente.
  4. Del objeto shopify salen appMetafields (lectura), applyMetafieldChange (escritura), instructions (qué está permitido) e i18n (textos traducidos).
  5. saved busca el metafield de carrito para precargar el campo si el cliente vuelve a este paso.
  6. Si canSetCartMetafields es falso, la extensión no se pinta. Shopify avisa de que con Apple Pay o Google Pay el cambio puede fallar.
  7. save guarda con updateCartMetafield o, si el cliente vació el campo, borra con removeCartMetafield. Corre en onBlur, no en cada tecla: la guía de rendimiento avisa de que demasiados cambios limitan la extensión.
  8. Si result.type es error, el campo muestra nuestro texto: el message del error no está localizado y Shopify pide no enseñárselo al cliente.
  9. updateValue es una función con nombre porque el validador rechazó la flecha dentro del JSX.
  10. El s-text-field recibe etiqueta, valor, error y los dos eventos. Los textos viven en locales/en.default.json y 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 }
  }
}
  1. namespace y key repiten los de la extensión; si difieren una letra, no hay copia.
  2. ownerType: ORDER define el metafield sobre pedidos, no sobre carritos.
  3. capabilities activa cartToOrderCopyable, la que copia el valor del carrito.
  4. 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.

los archivos de la extensión y el camino del valorshopify.extension.tomltarget y metafield solicitadosrc/Checkout.jsxel campo y applyMetafieldChangelocales/en.default.jsonlos textos del campocamino del valors-text-fieldel cliente escribeapplyMetafieldChangecart metafieldmy_app.po_referencecart_to_order_copyableorder metafieldmy_app.po_referenceal crear el pedidosin la definición del pedido, el valor se queda en el carritoel valor llega al pedido solo si existe la definicióndefinición de metafield de pedido con la copia desde el 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 muestraTarget de ejemploPlan
Paso de informaciónpurchase.checkout.contact.render-afterShopify Plus
Paso de envíopurchase.checkout.shipping-option-list.render-afterShopify Plus
Paso de pagopurchase.checkout.payment-method-list.render-afterShopify Plus
Página Thank youpurchase.thank-you.block.renderTodos 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 canSetCartMetafields y maneja el error; 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, KEY y el .toml coinciden 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 canSetCartMetafields y 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

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

← Blog