WooCommerce REST API: как создать и использовать кастомные поля в заказах

Диагностика проблемы: почему кастомные поля в заказах WooCommerce не отображаются через REST API

По умолчанию WooCommerce REST API возвращает стандартные поля заказа, но не выводит пользовательские метаданные (кастомные поля), которые часто нужны для интеграций, аналитики или дополнительной логики. Пользователи сталкиваются с тем, что добавленные вручную или плагинами поля не видны в ответе API, из-за чего интеграции и автоматизация оказываются неполными.

Пошаговое решение: добавляем кастомные поля в REST API заказов WooCommerce

1. Добавление метаполей к заказу через PHP

Для начала создадим и сохраним кастомное поле в заказе программно, если его еще нет. Например, добавим поле delivery_instructions — инструкции для доставки.

function add_custom_order_meta( $order_id ) {
    if ( ! get_post_meta( $order_id, '_delivery_instructions', true ) ) {
        update_post_meta( $order_id, '_delivery_instructions', 'Оставить у двери' );
    }
}
add_action( 'woocommerce_thankyou', 'add_custom_order_meta' );

2. Регистрация кастомного поля в REST API заказов

Чтобы поле появилось в ответах API, регистрируем его с помощью register_rest_field. Этот хук позволяет добавить любое поле к REST-ответу.

add_action( 'rest_api_init', function () {
    register_rest_field( 'shop_order', 'delivery_instructions', [
        'get_callback'    => function( $order ) {
            return get_post_meta( $order['id'], '_delivery_instructions', true );
        },
        'update_callback' => function( $value, $order ) {
            if ( ! is_string( $value ) ) {
                return;
            }
            update_post_meta( $order->ID, '_delivery_instructions', sanitize_text_field( $value ) );
        },
        'schema'         => [
            'description' => 'Инструкции для доставки',
            'type'        => 'string',
            'context'     => ['view', 'edit'],
        ],
    ]);
});

3. Проверка работы через REST API запрос

Сделайте GET-запрос к заказу по API, например:

curl -X GET https://example.com/wp-json/wc/v3/orders/123 \
    -u consumer_key:consumer_secret

В ответе должно появиться новое поле delivery_instructions с вашим значением.

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

• Отправьте запрос GET к заказу через REST API и убедитесь, что в JSON есть поле delivery_instructions.
• Попробуйте изменить значение этого поля через PATCH или PUT запрос и проверьте, что после обновления оно сохраняется в базе (через wp-admin или SQL).
• Проверьте, что остальные данные заказа при этом не повреждаются.

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

• Кастомное поле не отображается в API: убедитесь, что регистрация поля происходит на rest_api_init, а не раньше; проверьте, что тип объекта в register_rest_field — shop_order.
• Обновление поля через API не работает: проверьте, что update_callback корректно получает объект заказа и обновляет мета; используйте $order->ID, а не $order['id'] при обновлении.
• Ошибка авторизации при изменении данных: для обновления заказов через REST API нужен правильный ключ с правами записывать данные (write). Проверьте права ключа в WooCommerce.
• Проблемы с типами данных: всегда фильтруйте и проверяйте входящие данные, чтобы не записывать невалидные значения — используйте sanitize_text_field или аналогичные функции.

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

• Ограничьте контекст видимости поля в REST API только тем, где оно реально нужен, например context => ['view', 'edit'], чтобы не раскрывать лишние данные.
• Используйте nonce и проверку прав пользователя при обновлении данных через API, чтобы избежать несанкционированного изменения.
• Если в заказах много кастомных полей, подумайте о кешировании API ответов, чтобы снизить нагрузку.
• Не храните в метаполях чувствительные данные, если планируете их отдавать через публичный API.

Сравнение способов добавления кастомных полей в WooCommerce REST API

Способ	Плюсы	Минусы	Когда использовать
register_rest_field с колбэками	Гибкость, прямое управление, поддержка обновления через API	Требует написания кода, потенциально влияет на производительность при большом числе полей	Для кастомных полей с логикой и безопасным обновлением
Плагины для кастомных полей (ACF, Meta Box) с REST API расширением	Быстрая интеграция, удобный интерфейс	Зависимость от плагинов, менее гибко для нестандартных нужд	Если нужны простые поля без сложной логики
Добавление данных в описание заказа или дополнительные поля WooCommerce	Простота, не требует кода для API	Ограниченная структура, не всегда удобно для интеграций	Для минимальных изменений без необходимости API