Accessing Custom Metadata on WooCommerce Order Items
When working with WooCommerce, you often need to pull custom data stored in order items. This is common when developers have added custom fields to products and want to retrieve those values during checkout or after an order is placed. The standard approach using $order->get_data() or $order->get_item() frequently hits a wall when trying to access the meta_data property directly.
The core issue lies in how WooCommerce structures its data objects. While you can successfully access properties like ID, name, and quantity via get_data(), attempting to read meta_data triggers an UNCAUGHT ERROR: CANNOT USE OBJECT OF TYPE WC_DATETIME AS ARRAY IN. This error occurs because the internal data representation contains WC_DateTime objects, which behave differently from simple arrays or strings when accessed directly through the public API.
Furthermore, using get_item() often returns null for the meta_data field if that property is marked as protected within the class hierarchy. This happens because WooCommerce wraps metadata in a specific structure to handle serialization and deserialization correctly, preventing direct array access on the raw object.
To bypass these restrictions, you need to access the underlying data representation differently depending on your PHP version. In older versions of WooCommerce, the get_data() method returns an associative array. However, newer versions have stricter type hints that can cause issues if you try to manipulate the raw metadata array directly without converting it first.
The most reliable way to extract this information is to access the item object and then retrieve its metadata using the dedicated getter methods provided by the WC_Order_Item_Product class. Instead of trying to cast the entire item to an array, which breaks on protected properties like meta_data, you should explicitly call the method designed for it.
Here is the correct implementation pattern:
$order_id = 251; // The ID of the order you are working with
$order = wc_get_order( $order_id );
foreach ( $order->get_items() as $item ) {
// Get the raw metadata array safely
$metadata = $item->get_meta( true );
foreach ( $metadata as $meta_item ) {
$key = sanitize_key( $meta_item['key'] );
$value = $meta_item['value'];
if ( $key === 'my_car' && $value === 'red' ) {
// You can now safely use the custom data
echo "Car color is: " . esc_html( $value );
}
}
}
The critical function here is $item->get_meta( true ). Passing true as the second argument forces WooCommerce to return all metadata, including those marked as hidden or read-only. This method bypasses the protected property restrictions and avoids the type-casting errors associated with WC_DateTime objects found in the internal data array.
One common pitfall is trying to access $item->meta_data directly. While this might seem intuitive given the JSON structure you see in debug logs, it fails because the property is not exposed as a public attribute for modification or direct reading in all contexts. Additionally, dates stored within that metadata will be WC_DateTime objects. If your custom field stores timestamps, do not treat them as strings; use $meta_item['date']->format( 'Y-m-d' ) to extract the actual date string.
If you are migrating from older codebases or dealing with third-party plugins that rely on the deprecated direct array access pattern, updating your logic to use get_meta() is essential for stability. This approach ensures compatibility with future WooCommerce versions that may tighten security around order item data access.
For developers looking to build robust e-commerce features or integrate with external systems like LaravelCompany, ensuring you handle metadata retrieval this way prevents runtime errors and maintains data integrity across different server environments. Always sanitize keys and values before storing them in your own database or sending them via API calls.