WooCommerce REST API: работа с кастомными полями в заказах

Почему нужны кастомные поля в заказах WooCommerce через REST API

Стандартные поля заказа WooCommerce часто не покрывают всех бизнес-требований. Кастомные поля позволяют хранить дополнительную информацию, например, индивидуальные пожелания клиента, внутренние статусы или данные для интеграций. Через REST API управлять такими полями придется вручную, так как в базовом наборе API их нет.

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

Если вы пробовали добавить кастомные метаполя к заказу через стандартные REST-запросы, но данные не сохраняются, вероятно, вы не используете правильный подход с мета-данными или не зарегистрировали метаполя для REST API. WooCommerce по умолчанию не отдаёт и не принимает все метаполя.

Как проверить текущие метаполя заказа

Выполните GET-запрос к эндпоинту заказа, например:

GET /wp-json/wc/v3/orders/123?consumer_key=XXX&consumer_secret=YYY

Если ваши кастомные поля отсутствуют в ответе, значит, их нужно регистрировать для REST API.

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

1. Добавьте метаполя к заказам и зарегистрируйте их для REST API

Используйте хук register_meta для мета-данных заказа с параметром show_in_rest:

add_action('init', function() {
    register_meta('post', 'my_custom_order_field', [
        'type' => 'string',
        'description' => 'Моё кастомное поле заказа',
        'single' => true,
        'show_in_rest' => true,
        'sanitize_callback' => 'sanitize_text_field',
        'auth_callback' => function() {
            return current_user_can('edit_shop_orders');
        },
    ]);
});

Важно: указывайте post, так как заказы — это тип постов shop_order.

2. Добавьте кастомное поле к заказу в коде

Можно добавить поле при создании или обновлении заказа через REST API, передавая его в объекте meta_data:

POST /wp-json/wc/v3/orders/123
{
  "meta_data": [
    {
      "key": "my_custom_order_field",
      "value": "Значение кастомного поля"
    }
  ]
}

При создании заказа аналогично можно передавать meta_data с нужными ключами и значениями.

3. Получение кастомных полей через REST API

После регистрации метаполя и добавления данных они автоматически появятся в объекте заказа при GET-запросе в массиве meta_data:

GET /wp-json/wc/v3/orders/123

В ответе найдите элемент с ключом my_custom_order_field и его значением.

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

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

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

• Кастомное поле не сохраняется: не зарегистрировано с show_in_rest => true или неверно указан тип (должен быть 'post').
• Ошибка авторизации при обновлении метаданных: проверьте auth_callback в register_meta и права пользователя API.
• Поле не отображается в ответе API: проверьте, что поле передаётся в meta_data, а не в другом месте.
• Неверный формат JSON запроса: всегда используйте массив объектов с ключами key и value внутри meta_data.

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

• Регистрация метаполей с auth_callback ограничивает доступ только авторизованным пользователям с нужными правами.
• Не храните в кастомных полях чувствительные данные без шифрования.
• Избегайте больших объёмов данных в метаданных, чтобы не замедлять загрузку заказов.
• Для массового обновления заказов используйте пакетные запросы с ограничением скорости, чтобы не получить ошибку 429.

Сравнение вариантов работы с кастомными полями в заказах WooCommerce