Eigene WooCommerce-Checkout-Felder: hinzufügen, speichern, validieren

Ein eigenes Checkout-Feld ist nicht fertig, nur weil es auf der Seite steht. Es muss die Übermittlung überstehen, in der Bestellung landen und ausschließlich Daten ablehnen, die eine Erfüllung tatsächlich verhindern. Fehlt der Save-Hook, schließt der Kunde den Checkout ab, doch der Wert geht verloren. Ist die Validierung zu eng, scheitern gute Bestellungen im letzten Schritt.

Dieser Guide führt durch den gesamten Ablauf mit praxistauglichem Code. Dazu gehören die abweichenden Regeln für Checkout-Blöcke und Express-Zahlungsbuttons.

Bestehende Felder entfernen und umsortieren

Entferne einen Key mit unset und setze priority zum Verschieben:

add_filter( 'woocommerce_checkout_fields', 'sm_trim_checkout_fields' );

function sm_trim_checkout_fields( $fields ) {
	// Drop fields this store genuinely does not use.
	unset( $fields['billing']['billing_company'] );
	unset( $fields['billing']['billing_address_2'] );

	// Move contact details above the address block.
	$fields['billing']['billing_email']['priority'] = 21;
	$fields['billing']['billing_phone']['priority'] = 22;

	// Widen the remaining rows.
	$fields['billing']['billing_email']['class'] = array( 'form-row-wide' );

	return $fields;
}

Priority steuert die Reihenfolge innerhalb einer Gruppe, nicht auf der ganzen Seite. Eine Änderung bei billing betrifft shipping nicht. Die eingebauten Felder lassen oft Zehnerschritte frei. Mit 21 und 22 liegen beide Felder zwischen Nachname (20) und Firma (30), ohne andere Felder zu verschieben.

Umsortieren ist meist risikoarm. Für das Entfernen eines Feldes brauchst du einen klaren Grund.

Diese Felder solltest du behalten, auch wenn sie verzichtbar wirken:

• billing_country und billing_postcode, weil Steuer- und Versandberechnung diese Angaben brauchen
• billing_phone bei physischer Ware, wenn der Versanddienst eine Kontaktmöglichkeit braucht
• billing_email als verlässliche Kennung für Gastbestellungen
• Jedes Feld, das Rechnungs-, Buchhaltungs- oder Fulfillment-Software erwartet. Das Entfernen kann Exporte brechen, obwohl der Checkout noch sauber aussieht

Eigene Felddaten in der Bestellung speichern

Ein ausgegebenes Feld ohne Save-Hook erfasst nichts. Der Checkout läuft trotzdem durch. Genau deshalb bleibt dieser Fehler leicht unbemerkt.

Der Save-Hook

Speichere über das Bestellobjekt in woocommerce_checkout_create_order. Dieser Hook läuft, bevor WooCommerce die Bestellung schreibt:

add_action( 'woocommerce_checkout_create_order', 'sm_save_custom_checkout_fields', 10, 2 );

function sm_save_custom_checkout_fields( $order, $data ) {
	// WooCommerce has already verified its own checkout nonce at this point.
	if ( ! empty( $_POST['sm_vat_number'] ) ) {
		$order->update_meta_data(
			'_sm_vat_number',
			sanitize_text_field( wp_unslash( $_POST['sm_vat_number'] ) )
		);
	}

	if ( ! empty( $_POST['sm_delivery_notes'] ) ) {
		$order->update_meta_data(
			'_sm_delivery_notes',
			sanitize_textarea_field( wp_unslash( $_POST['sm_delivery_notes'] ) )
		);
	}

	// Never trust a posted option value. Compare it against your own list.
	$window  = isset( $_POST['sm_delivery_window'] ) ? sanitize_key( wp_unslash( $_POST['sm_delivery_window'] ) ) : '';
	$allowed = array( 'morning', 'evening' );

	if ( in_array( $window, $allowed, true ) ) {
		$order->update_meta_data( '_sm_delivery_window', $window );
	}

	// An unchecked checkbox posts nothing, so write both states explicitly.
	$order->update_meta_data( '_sm_gift_wrap', isset( $_POST['sm_gift_wrap'] ) ? 'yes' : 'no' );
}

Rufe hier kein $order->save() auf. WooCommerce speichert die Bestellung direkt nach diesem Hook. Das Bestellobjekt statt update_post_meta() hält den Code kompatibel mit HPOS-Bestellspeicherung, bei der die posts-Tabelle nicht mehr die maßgebliche Ablage für Bestellungen ist.

Wenn du Code am älteren Hook woocommerce_checkout_update_order_meta übernimmst, musst du ihn nicht sofort ersetzen. Du musst aber die CRUD-Schicht verwenden:

add_action( 'woocommerce_checkout_update_order_meta', 'sm_legacy_save_custom_fields' );

function sm_legacy_save_custom_fields( $order_id ) {
	$order = wc_get_order( $order_id );

	if ( ! $order || empty( $_POST['sm_vat_number'] ) ) {
		return;
	}

	$order->update_meta_data( '_sm_vat_number', sanitize_text_field( wp_unslash( $_POST['sm_vat_number'] ) ) );
	$order->save();
}

Anzeige im Admin-Bestellbildschirm

Meta-Keys mit führendem Unterstrich bleiben im allgemeinen Custom-Fields-Panel verborgen. Gib sie daher gezielt aus:

add_action( 'woocommerce_admin_order_data_after_billing_address', 'sm_show_custom_fields_in_admin' );

function sm_show_custom_fields_in_admin( $order ) {
	$vat    = $order->get_meta( '_sm_vat_number' );
	$window = $order->get_meta( '_sm_delivery_window' );

	if ( $vat ) {
		echo '<p><strong>' . esc_html__( 'VAT number', 'my-store' ) . ':</strong> ' . esc_html( $vat ) . '</p>';
	}

	if ( $window ) {
		echo '<p><strong>' . esc_html__( 'Delivery window', 'my-store' ) . ':</strong> ' . esc_html( $window ) . '</p>';
	}
}

Nutze $order->get_meta() statt get_post_meta(), aus demselben HPOS-Grund wie beim Save-Hook.

In Bestell-E-Mails einbinden

Dieser Filter hängt deine Felder an die Metatabelle von WooCommerce-Bestell-E-Mails:

add_filter( 'woocommerce_email_order_meta_fields', 'sm_email_order_meta_fields', 10, 3 );

function sm_email_order_meta_fields( $fields, $sent_to_admin, $order ) {
	$vat = $order->get_meta( '_sm_vat_number' );

	if ( $vat ) {
		$fields['sm_vat_number'] = array(
			'label' => __( 'VAT number', 'my-store' ),
			'value' => $vat,
		);
	}

	return $fields;
}

Prüfe $sent_to_admin, wenn ein Wert nur in die interne E-Mail gehört. Der Filter steuert die Template-Ausgabe. Künftig kann ShopMonitor die Zustellung transaktionaler E-Mails separat testen.

Plugin-Alternativen

Code gibt dir präzise Kontrolle. Ein Plugin gibt Teams ohne technisches Fachwissen eine Admin-Oberfläche. Dieser Unterschied zählt mehr, als viele Teams erwarten.

Die offizielle Erweiterung Checkout Field Editor bietet eine Tabelle für Rechnungs-, Versand- und Zusatzfelder. Du kannst Felder hinzufügen, entfernen, sortieren, umbenennen und Typen wie Select, Radio, Checkbox oder Datum ändern. ThemeHighs Checkout Field Editor bietet ähnliche Funktionen. Die kostenlose Variante ist eingeschränkt, die kostenpflichtige enthält bedingte Logik. Beide speichern Felddefinitionen in der Options-Tabelle außerhalb deiner Versionskontrolle. Wird das Plugin deaktiviert, greifen diese Definitionen nicht mehr.

Entscheidung Code vs. Plugin

Die Plugin-Route ist sinnvoll, wenn:

• Niemand im Team PHP sicher veröffentlichen kann
• Sich das Feldset mit Kampagnen oder Saisons ändert
• Du einen Datepicker oder ein bedingtes Feld ohne JavaScript-Pflege brauchst
• Die Alternative wäre ein Snippet im Parent-Theme, das das nächste Update überschreibt