Personalizzare i campi del checkout WooCommerce

Per modificare i campi del checkout WooCommerce oggi ci sono due strade, e quale usare dipende da come è costruita la tua pagina di checkout. Se usi il checkout a blocchi, i campi aggiuntivi si registrano con la funzione woocommerce_register_additional_checkout_field(). Se usi ancora il checkout classico a shortcode, si continua a lavorare con il filtro woocommerce_checkout_fields.

Confondere le due strade è l'errore più comune: il codice scritto per il checkout classico non produce alcun effetto sul checkout a blocchi, e la cosa non genera nessun messaggio di errore. Il campo semplicemente non compare.

Cosa si può fare su ogni campo

Prima di scrivere codice conviene decidere l'intervento minimo necessario. Su molti shop la metà delle richieste si risolve senza PHP.

La riga più importante è l'ultima. Aggiungere un campo è l'unica operazione che richiede quasi sempre codice, ed è anche quella dove le due architetture divergono di più.

Checkout a blocchi: registrare un campo aggiuntivo

L'API dei campi aggiuntivi è stata introdotta con WooCommerce 8.6 ed è oggi il modo supportato per estendere il checkout a blocchi. La registrazione va agganciata all'azione woocommerce_init, altrimenti WooCommerce non è ancora pronto ad accettarla.

add_action( 'woocommerce_init', function () {
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'obly/citofono',
            'label'    => 'Nome sul citofono',
            'location' => 'address',
            'type'     => 'text',
            'required' => false,
        )
    );
} );

Tre parametri sono obbligatori: id, label e location. L'id deve essere in forma namespace/nome-campo, dove il namespace è tuo (il nome del plugin o dell'azienda) e serve a evitare collisioni con altre estensioni.

Il parametro location decide dove il campo compare e come viene salvato:

1. contact: nella sezione dei dati di contatto, in alto. È il posto giusto per un consenso, un secondo recapito o una preferenza di contatto.
2. address: dentro il blocco indirizzo, sia di fatturazione sia di spedizione. Il campo viene chiesto due volte se il cliente usa indirizzi diversi, ed è il comportamento corretto per informazioni legate al luogo, come piano, interno o nome sul citofono.
3. order: nella sezione delle informazioni aggiuntive dell'ordine. Adatto a tutto ciò che riguarda l'ordine nel suo insieme, come la richiesta di confezione regalo o una data di consegna preferita.

I tipi di campo supportati sono tre: text, select e checkbox. Per un menu a tendina si passa anche l'elenco delle opzioni.

add_action( 'woocommerce_init', function () {
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'obly/fascia-consegna',
            'label'    => 'Fascia oraria preferita',
            'location' => 'order',
            'type'     => 'select',
            'required' => false,
            'options'  => array(
                array( 'value' => 'mattina',    'label' => 'Mattina (9-13)' ),
                array( 'value' => 'pomeriggio', 'label' => 'Pomeriggio (14-18)' ),
            ),
        )
    );
} );

Non serve scrivere codice per salvare il valore: WooCommerce lo persiste da solo sull'ordine e, quando il campo è legato al cliente, anche sul profilo, così al secondo acquisto risulta già compilato.

Dove finiscono i valori sull'ordine

I valori vengono salvati come metadati con un prefisso che dipende dal gruppo del campo: _wc_billing/ per i campi di fatturazione, _wc_shipping/ per quelli di spedizione e _wc_other/ per i campi di contatto e di ordine, seguito dall'id registrato.

Il campo obly/fascia-consegna dell'esempio precedente finisce quindi in _wc_other/obly/fascia-consegna. Sapere questa regola serve in tre momenti pratici: quando esporti gli ordini in CSV, quando li passi a un gestionale o a un sistema di spedizioni, e quando vuoi mostrare il valore nella mail di conferma. Se stai mettendo mano proprio a quelle comunicazioni, il punto di partenza sono le email transazionali di WooCommerce.

Checkout classico: il filtro sui campi

Sugli shop che usano ancora lo shortcode, il filtro woocommerce_checkout_fields resta valido e continua a funzionare. Riceve un array con tre gruppi: billing, shipping e order.

add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
    // Rimuove un campo che non serve
    unset( $fields['billing']['billing_company'] );

    // Rende opzionale un campo obbligatorio
    $fields['billing']['billing_phone']['required'] = false;

    // Cambia etichetta e posizione
    $fields['order']['order_comments']['label']    = 'Istruzioni per il corriere';
    $fields['order']['order_comments']['priority'] = 10;

    return $fields;
} );

La chiave priority controlla l'ordine di stampa: numeri più bassi salgono in alto. I campi anagrafici standard usano valori distanziati di dieci, quindi conviene usare numeri intermedi per infilare un campo tra due esistenti senza riscrivere l'intera scala.

Vale la pena ricordare che questo codice, su un sito già migrato al checkout a blocchi, non produce alcun effetto. Se stai pianificando la migrazione, la conversione dei campi personalizzati va messa in preventivo insieme al resto.

Quali campi togliere davvero

La tentazione di ridurre il checkout all'osso è forte, e in generale meno campi significano meno abbandoni. Ci sono però tre categorie da non toccare a cuor leggero.

I campi che alimentano il calcolo delle imposte, come paese, provincia e CAP, servono a WooCommerce per applicare l'aliquota giusta. Se li rimuovi o li rendi opzionali, il totale mostrato può risultare sbagliato: il tema è trattato per esteso nella guida alle aliquote IVA in WooCommerce.

I campi richiesti dal corriere, tipicamente il numero di telefono, sembrano superflui finché non arriva la prima consegna fallita. Molti corrieri usano SMS o chiamate per gestire il secondo tentativo, e senza recapito il pacco torna indietro a tue spese.

I dati fiscali sono il caso più delicato sul mercato italiano. Codice fiscale, partita IVA, codice destinatario e PEC vanno raccolti al momento dell'ordine, perché recuperarli via email dopo significa rincorrere il cliente per giorni. Come impostarli correttamente è spiegato nell'articolo sulla fatturazione elettronica.

Tutto il resto è negoziabile. Il campo azienda, il secondo rigo dell'indirizzo e le note ordine possono quasi sempre diventare opzionali o sparire.

Validazione: fermarsi al momento giusto

Un campo senza validazione produce dati che nessuno userà. Se chiedi una data di consegna e accetti testo libero, ti ritroverai "quando potete" nel campo, e il valore diventa inutile per qualsiasi automazione a valle.

Sul checkout a blocchi la validazione lato server si aggancia agli hook dedicati ai campi aggiuntivi, che ricevono il valore e permettono di restituire un errore mostrato accanto al campo. Sul checkout classico l'equivalente è l'azione di validazione del processo di checkout, dove si aggiunge un avviso di errore quando il valore non rispetta il formato atteso.

In entrambi i casi vale una regola pratica: valida sempre lato server, anche quando hai già un controllo nel browser. Il controllo lato client migliora l'esperienza, ma non è una barriera affidabile.

Errori comuni

• Registrare il campo senza agganciarlo a woocommerce_init: la registrazione viene ignorata in silenzio.
• Usare un id senza namespace: rischi conflitti con altri plugin e la registrazione può essere rifiutata.
• Aggiungere campi obbligatori in address dimenticando che verranno chiesti sia in fatturazione sia in spedizione: il cliente si trova a compilare due volte la stessa cosa.
• Mettere in cache la pagina di checkout: campi condizionali e totali smettono di aggiornarsi. Il checkout va sempre escluso dalla cache.
• Testare solo con un prodotto virtuale: senza spedizione metà dei campi non compare, e i problemi emergono al primo ordine fisico.
• Aggiungere campi senza chiedersi chi li leggerà: ogni campo in più abbassa il tasso di completamento, e il costo si vede nella coda dei carrelli abbandonati.

In sintesi

Il criterio è semplice: prima verifica quale checkout stai usando, poi prova a ottenere il risultato dalle impostazioni del blocco, e solo alla fine scrivi codice. Quando il codice serve, usa l'API dei campi aggiuntivi sul checkout a blocchi e il filtro sui campi su quello classico, senza mescolare i due approcci.

Quando configuriamo uno shop, partiamo sempre dall'elenco dei dati che servono davvero a valle, spedizione, fatturazione e assistenza, e costruiamo il checkout su quello. Ogni campo deve avere qualcuno che lo legge: se non riesci a dire chi, quel campo non serve.