WooCommerce Custom Fields to API Match

Yes, WooCommerce custom fields can be matched to your API, but the process is not automatic—you need to map each custom field to a corresponding API parameter using hooks, plugins, or custom code. This article explains exactly how the matching works, what tools to use, and the common pitfalls to avoid.

What Are WooCommerce Custom Fields?

Custom fields (also called post meta) are extra data fields attached to products, orders, or checkout forms. By default, WooCommerce stores standard data like billing address, shipping address, and payment method. Custom fields let you collect additional information such as a customer’s preferred delivery time, a gift message, or a company tax ID.

These fields are stored in the WordPress database as key-value pairs. For example, a field with the label “Delivery Date” might be stored with the key _delivery_date and the value 2025-06-15. When you need to send this data to an external API (like a CRM, ERP, or shipping service), you must tell WooCommerce which custom field corresponds to which API field.

How Checkout Custom Fields Are Saved

When a customer checks out, WooCommerce triggers a series of actions. The most important one for custom fields is woocommerce_checkout_update_order_meta, which fires after the order is created. At this point, you can save any custom field value to the order using the update_post_meta() function.

For example, if you added a checkout field named delivery_date, you would save it like this:

add_action( 'woocommerce_checkout_update_order_meta', 'save_delivery_date' );
function save_delivery_date( $order_id ) {
    if ( ! empty( $_POST['delivery_date'] ) ) {
        update_post_meta( $order_id, '_delivery_date', sanitize_text_field( $_POST['delivery_date'] ) );
    }
}

Once saved, the custom field becomes part of the order’s metadata. To send it to an API, you need to retrieve that metadata and include it in the API request payload.

Matching Custom Fields to API Parameters

Matching means defining a mapping between your custom field keys and the API’s expected field names. For example, if your API expects a parameter called deliveryDate, you need to tell your integration code to take the value from _delivery_date and put it under deliveryDate.

Here’s a simple PHP snippet that does this when sending order data to an external API:

$order = wc_get_order( $order_id );
$delivery_date = get_post_meta( $order_id, '_delivery_date', true );

$api_data = array(
    'order_id'    => $order->get_id(),
    'deliveryDate' => $delivery_date,
    // ... other fields
);

// Send $api_data to your API endpoint

This is the core of matching: you explicitly assign each custom field to an API field. The same logic applies whether you’re using a plugin, a webhook, or a custom integration.

Tools to Automate the Mapping

You don’t have to write all the code yourself. Several approaches exist, depending on your technical comfort:

• Custom code: Write a function hooked to woocommerce_api_create_order or use the REST API’s meta_data field. This gives you full control.
• Plugins like WP Webhooks or Zapier: These allow you to map fields visually. You select the WooCommerce field (including custom fields) and the API field, and the plugin handles the rest.
• WooCommerce REST API: The built-in REST API returns order metadata in the meta_data array. You can then write a script that transforms that array into your API’s format.

For example, with the REST API, an order’s custom fields appear like this:

"meta_data": [
    {
        "id": 123,
        "key": "_delivery_date",
        "value": "2025-06-15"
    }
]

Your integration code can loop through this array and build the API payload accordingly.

Common Problems and How to Avoid Them

Even with a clear mapping, things can go wrong. Here are the most frequent issues:

• Field keys not saved: If your custom field is not being saved, check that you’re using the correct hook and that the field name matches the name attribute in your HTML.
• Data type mismatches: An API might expect an integer, but your custom field is stored as a string. Convert the value before sending (e.g., (int)$value).
• Undefined fields: If the customer leaves a field empty, the meta may not exist. Use get_post_meta with a default value or check with empty().
• API rate limits: If you’re sending many orders, you may hit rate limits. Batch your requests or use a queue system.

A common misconception is that custom fields are automatically included in API requests. They are not. You must explicitly retrieve and include them.

Security and Data Validation

When handling custom fields, always validate and sanitize the data before saving or sending. Use sanitize_text_field() for text, sanitize_email() for emails, and absint() for integers. This prevents malicious input from reaching your API.

Also, be careful with sensitive data. If a custom field contains personal information, ensure your API connection uses HTTPS and that you comply with data protection regulations. Never log full API payloads with sensitive data.

Frequently Asked Questions

Do I need a plugin to match custom fields to an API?

No. You can do it with custom code using WordPress hooks and the REST API. Plugins simplify the process if you prefer a visual interface, but they are not required.

Can I use the WooCommerce REST API to send custom fields?

Yes. The REST API returns order metadata in the meta_data array. You can read that array and map it to your API’s fields in your integration code.

What if my API expects a different field name than my custom field?

You simply map the names in your code. For example, if your custom field is _gift_message and the API expects message, you assign 'message' => $gift_message in the payload.

Why is my custom field not showing up in the API request?

Most likely because you haven’t explicitly included it. Check that the meta key is saved correctly and that your code retrieves it before building the request.

Can I match custom fields to an API using a webhook?

Yes. Webhook services like Zapier or WP Webhooks allow you to map fields visually. You select the custom field as the source and the API field as the destination.

Is it safe to send custom fields to an external API?

It is safe if you validate the data, use HTTPS, and only send necessary information. Avoid sending sensitive data unless required and ensure the API provider is trustworthy.

Related

• Programming First Time: 12 Things I Wish I Knew
• Measure AI Automation’s CX Impact: A Guide
• 16GB RAM Not Enough for Gamers?