WooCommerce Checkout Blocks: как добавить поля без старых checkout hooks

Многие доработки WooCommerce годами добавляли поля оформления заказа через фильтры и actions классического shortcode checkout. После перехода магазина на Cart и Checkout Blocks такой код может не отображаться или работать только частично, потому что блоковый checkout использует другую архитектуру и Store API.

Для современных Checkout Blocks WooCommerce предоставляет официальный Additional Checkout Fields API. Он позволяет зарегистрировать поле, выбрать его место, выполнить sanitization и validation и сохранить значение в заказе или профиле покупателя без ручной синхронизации JavaScript с PHP.

Почему старый checkout-код нельзя переносить вслепую

Официальная документация WooCommerce отдельно отмечает, что часть классических примеров изменения checkout fields относится именно к shortcode Checkout. Для Checkout Block следует использовать Additional Checkout Fields.

Поэтому перед доработкой сначала проверьте, какой checkout реально используется на странице. Если это блок, попытка добавить HTML через legacy hook может вообще не попасть в интерфейс или не участвовать в Store API checkout request.

Базовая регистрация поля

Поле регистрируется функцией woocommerce_register_additional_checkout_field(). WooCommerce рекомендует делать это на woocommerce_init или позже.

add_action( 'woocommerce_init', function () {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }

    woocommerce_register_additional_checkout_field( [
        'id'       => 'asgroups/company-vat',
        'label'    => 'VAT number',
        'location' => 'address',
        'type'     => 'text',
        'required' => false,
    ] );
} );

ID должен содержать namespace и имя поля через /. Это снижает риск конфликта с другим плагином и используется при работе со значением через API.

Три location: contact, address и order

Выбор location определяет не только место в форме, но и дальнейшее хранение данных.

• contact — поле относится к контактной информации и может сохраняться для аккаунта покупателя;
• address — поле добавляется к адресу и сохраняется в контексте customer/order; для него существуют shipping и billing значения;
• order — данные относятся к конкретному заказу, например комментарий к подарку или внутренний бизнес-параметр оформления.

Не выбирайте location только по визуальному месту. Сначала определите жизненный цикл данных: нужно ли значение повторно использовать для следующего заказа или оно относится только к текущей покупке.

Важная особенность address

Поле location address появляется в shipping и billing address. Нельзя зарегистрировать его этим способом только для одной из двух форм. WooCommerce хранит два значения независимо, даже если покупатель использует одинаковый адрес.

Если бизнес-задача требует единственное поле на заказ, например номер пропуска или текст для курьера, чаще логичнее location order.

Поддерживаемые типы полей

Актуальная документация перечисляет типы text, select, checkbox и date. Для select задаются options, для text можно использовать допустимые HTML attributes, а date поддерживает ограничения min/max.

Если нужен сложный UI с несколькими связанными контролами, загрузкой файла или собственной интерактивностью, не стоит пытаться маскировать его под обычное text-поле. В таком случае нужно отдельно проектировать расширение Checkout Block и передачу данных в Store API.

Пример поля выбора

woocommerce_register_additional_checkout_field( [
    'id'       => 'asgroups/delivery-window',
    'label'    => 'Delivery window',
    'location' => 'order',
    'type'     => 'select',
    'options'  => [
        [ 'value' => 'morning', 'label' => 'Morning' ],
        [ 'value' => 'evening', 'label' => 'Evening' ],
    ],
] );

Такое поле становится частью штатного checkout flow, а не отдельным DOM-элементом, значение которого приходится вручную искать JavaScript-кодом перед отправкой заказа.

Sanitization и validation — разные этапы

Sanitization приводит значение к ожидаемому формату: например, убирает лишние пробелы или нормализует регистр. Validation отвечает на другой вопрос — допустимо ли значение по бизнес-правилам.

Не смешивайте эти задачи. Если VAT ID нужно привести к верхнему регистру, это sanitization. Если после нормализации он должен соответствовать конкретному шаблону или внешней проверке, это validation.

Required не всегда должен быть статическим

В современных версиях API условия required и hidden могут описываться через JSON Schema-подобные условия. Это позволяет, например, требовать дополнительное поле только для определённой страны или показывать второе поле после выбора конкретной опции.

Такой подход лучше, чем скрывать обязательный input только CSS: сервер и клиент получают согласованное правило, а не две независимые реализации.

Где сохраняются значения

WooCommerce сохраняет дополнительные поля в meta и предоставляет helper methods для чтения. Документация рекомендует использовать helpers вместо жёсткой привязки к внутреннему meta key: это уменьшает зависимость от будущих изменений хранения.

Для интеграции с CRM или ERP сначала определите, какое location использовано и где ожидается значение. Затем передавайте его во внешний сервис после создания заказа, например через webhook или собственный обработчик. О построении надёжной передачи заказов я писал отдельно в статье про WooCommerce webhooks.

Checkout Block и Store API связаны

Блоковый checkout работает через Store API, поэтому зарегистрированные поля участвуют в структуре checkout/customer данных. Это принципиальное отличие от старого подхода, где разработчик мог просто вывести input и затем вручную забрать $_POST.

Если магазин использует отдельный headless frontend, значения дополнительных полей также нужно передавать в структуре Store API согласно location. Базовую архитектуру Cart-Token и checkout я разобрал в материале WooCommerce Store API для headless-корзины.

Совместимость с версиями WooCommerce

Не копируйте код API без проверки версии WooCommerce. Официальный актуальный tutorial для дополнительных полей указывает минимальную версию WooCommerce 8.9.0 для описанного стабильного подхода. Если поддерживается более старый магазин, нужен version guard и отдельная стратегия.

Практический минимум — проверять существование woocommerce_register_additional_checkout_field() перед вызовом. Это безопаснее, чем получить fatal error после обновления темы или переноса кода на другой проект.

Не кладите бизнес-логику в тему без необходимости

Поле, связанное с бизнес-процессом магазина, лучше оформлять как небольшой отдельный plugin или MU-plugin. Тогда оно не исчезнет при смене темы и его проще тестировать, версионировать и переносить.

Child theme подходит для визуальных изменений, но логика VAT, доставки, B2B-реквизитов или интеграции с CRM обычно должна жить отдельно от шаблона.

Что проверить перед production

• Checkout действительно использует блоковую версию;
• поле зарегистрировано не раньше woocommerce_init;
• ID имеет уникальный namespace;
• правильно выбран location;
• required и hidden проверены и на клиенте, и сервером;
• значение проходит sanitization;
• ошибочное значение блокирует checkout понятным сообщением;
• данные появились в заказе и, где нужно, в аккаунте покупателя;
• guest checkout и logged-in checkout протестированы отдельно;
• проверены checkout emails, order admin и интеграции;
• кэш и оптимизация JavaScript не ломают Checkout Block.

Когда нужна отдельная доработка

Стандартный Additional Checkout Fields API закрывает много задач: VAT, согласия, дополнительные инструкции, даты и выбор из списка. Но зависимые поля, внешняя валидация, сложные B2B-реквизиты и интеграция с учётной системой требуют аккуратной серверной логики и тестирования полного checkout flow.

Если после перехода на Checkout Blocks пропали старые поля или нужно добавить новые без ломки оформления заказа, можно обратиться в A.S Groups. Проверю текущую реализацию, версию WooCommerce, Store API и существующие hooks и перенесу логику на поддерживаемый блоковый API без дублирования данных.