Как использовать хук WooCommerce checkout_update_order_meta для добавления данных к заказу

Что такое хук woocommerce_checkout_update_order_meta и зачем он нужен

Этот хук вызывается сразу после оформления заказа в WooCommerce, когда данные заказа уже созданы, но еще не сохранены полностью. Он позволяет добавить или изменить метаданные (custom fields) заказа, добавлять пользовательские данные из формы оформления или интегрировать дополнительную логику на этапе завершения покупки.

Диагностика задачи: почему необходимо использовать woocommerce_checkout_update_order_meta

Часто нужно добавить дополнительные поля на страницу оформления заказа, например, номер договора, комментарии, индивидуальные параметры товара. Чтобы эти данные сохранились в заказе, следует использовать именно этот хук. Если этого не сделать, пользовательские поля не сохранятся и не будут доступны в админке и в уведомлениях.

Как проверить, что данные не сохраняются

• Добавьте простое текстовое поле в форму оформления (например, через woocommerce_checkout_fields).
• Оформите заказ, заполнив это поле.
• Проверьте в админке WooCommerce — если поле пустое, значит, данные не сохраняются.

Пошаговое решение: добавление пользовательского поля и сохранение его через хук

1. Добавляем поле на страницу оформления

add_filter('woocommerce_checkout_fields', 'wpstandart_add_custom_checkout_field');
function wpstandart_add_custom_checkout_field($fields) {
    $fields['billing']['billing_contract_number'] = array(
        'type'        => 'text',
        'label'       => 'Номер договора',
        'required'    => true,
        'class'       => array('form-row-wide'),
        'priority'    => 120,
    );
    return $fields;
}

2. Сохраняем данные в мета заказа с помощью woocommerce_checkout_update_order_meta

add_action('woocommerce_checkout_update_order_meta', 'wpstandart_save_contract_number');
function wpstandart_save_contract_number($order_id) {
    if (!empty($_POST['billing_contract_number'])) {
        update_post_meta($order_id, '_billing_contract_number', sanitize_text_field($_POST['billing_contract_number']));
    }
}

3. Отображаем сохраненное поле в админке заказа

add_action('woocommerce_admin_order_data_after_billing_address', 'wpstandart_display_contract_number_admin_order', 10, 1);
function wpstandart_display_contract_number_admin_order($order){
    $contract_number = get_post_meta($order->get_id(), '_billing_contract_number', true);
    if ($contract_number) {
        echo '<p><strong>Номер договора:</strong> ' . esc_html($contract_number) . '</p>';
    }
}

Проверка результата после внедрения

• Очистите кеш сайта, если используется.
• Перейдите в оформление заказа и заполните новое поле «Номер договора».
• Завершите покупку.
• В админке WooCommerce откройте созданный заказ и убедитесь, что поле «Номер договора» отображается корректно.
• Дополнительно проверьте данные в базе, например, через phpMyAdmin, в таблице wp_postmeta должен появиться ключ _billing_contract_number с вашим значением.

Частые ошибки и как их исправить

• Поле не отображается на странице оформления — проверьте корректность хука woocommerce_checkout_fields и приоритеты, а также отсутствие конфликтов с темой или плагинами.
• Данные не сохраняются — убедитесь, что в форме поле имеет правильный name (совпадает с ключом в $_POST) и что функция сохранения подключена к woocommerce_checkout_update_order_meta.
• Безопасность данных — всегда используйте sanitize_text_field или другие функции очистки данных перед сохранением.
• Ошибка отображения в админке — проверяйте, что используете правильные хуки для вывода, например, woocommerce_admin_order_data_after_billing_address.

Практические советы по производительности и безопасности

• Если поле необязательное, всегда проверяйте через empty(), чтобы избежать записи пустых значений.
• Для сложных данных используйте JSON с последующим json_encode и json_decode, но храните в одной мета-записи.
• Не храните чувствительные данные без шифрования, особенно если они будут доступны в админке.
• Кэшируйте данные мета, если часто используете их в шаблонах фронтенда.

Таблица сравнения способов добавления пользовательских данных в заказ