WooCommerce CRUD & Data Stores
Before writing code
Fetch live docs:
- Web-search
site:developer.woocommerce.com crud data stores for CRUD documentation
- Web-search
site:github.com woocommerce woocommerce HPOS for HPOS architecture
- Fetch
https://github.com/woocommerce/woocommerce/wiki for architecture decisions
CRUD Architecture
Data Objects
WooCommerce's core entities extend WC_Data:
WC_Product — products (and subtypes: WC_Product_Simple, WC_Product_Variable, etc.)
WC_Order — orders (and WC_Order_Refund)
WC_Customer — customer profiles
WC_Coupon — discount coupons
WC_Shipping_Zone — shipping zones
WC_Data Base Class
All CRUD objects inherit from WC_Data:
$data — array of core properties with defaults
$meta_data — array of WC_Meta_Data objects
$id — object ID
$object_type — string identifier (e.g., 'product', 'order')
$data_store — the WC_Data_Store instance handling persistence
Getters and Setters
get_{prop}( $context = 'view' ) — retrieve a property
'view' context — runs woocommerce_{object_type}_get_{prop} filter (for display)
'edit' context — returns raw stored value (for forms/admin)
set_{prop}( $value ) — set a property (in memory, not persisted until save())
save() — persist to database (calls data store's create() or update())
delete( $force_delete ) — remove from database
Meta Data
get_meta( $key, $single, $context ) — get meta value
update_meta_data( $key, $value, $meta_id ) — set meta (in memory)
delete_meta_data( $key ) — mark meta for deletion
save_meta_data() — persist meta changes (called automatically by save())
Data Stores
What Data Stores Do
Data stores abstract the persistence layer. The CRUD object calls generic methods (read, create, update, delete) on its data store, which handles the actual SQL.
Built-In Data Stores
| Object |
Data Store |
Storage |
| Product |
WC_Product_Data_Store_CPT |
wp_posts + wp_postmeta |
| Order (legacy) |
WC_Order_Data_Store_CPT |
wp_posts + wp_postmeta |
| Order (HPOS) |
Automattic\WooCommerce\Internal\DataStores\Orders\OrdersTableDataStore |
wp_wc_orders + related tables |
| Customer |
WC_Customer_Data_Store |
wp_users + wp_usermeta |
| Coupon |
WC_Coupon_Data_Store_CPT |
wp_posts + wp_postmeta |
Custom Data Stores
You can swap data stores via the woocommerce_{object}_data_store filter:
- Implement
WC_Object_Data_Store_Interface (or extend an existing data store)
- Implement methods:
create(), read(), update(), delete(), read_meta(), update_meta(), delete_meta()
- Filter:
add_filter( 'woocommerce_product_data_store', function() { return 'My_Custom_Store'; } )
HPOS (High-Performance Order Storage)
What Changed
HPOS moves order data from wp_posts/wp_postmeta to dedicated tables:
wp_wc_orders — core order fields (status, currency, total, customer_id, dates)
wp_wc_orders_meta — order meta
wp_wc_order_addresses — billing/shipping addresses
wp_wc_order_operational_data — internal operational data
Why HPOS
- Massive performance improvement for stores with many orders
- Orders no longer pollute the
wp_posts table
- Dedicated indexes for order queries
- Cleaner separation of concerns
Compatibility Modes
- Sync enabled — both posts and custom tables are written (transition period)
- Authoritative: Custom tables — custom tables are the source of truth
- Authoritative: Posts — legacy mode, posts are source of truth
Sync-on-read is off by default
This is the failure mode to design against. WooCommerce disabled HPOS sync on read by default in the 10.7 release cycle. Code that writes order data straight into wp_postmeta and expects it to appear in HPOS now fails silently — no error, no warning, just data that is never read back.
The practical consequence: legacy order writes are not merely discouraged any more, they are broken. Auditing a plugin for direct wp_postmeta order writes is no longer a tidiness exercise, it is a correctness fix.
Confirm the current default and the exact release in the live docs — fetch https://developer.woocommerce.com/docs/features/orders/high-performance-order-storage/ — but write code as though sync is off regardless of version. It is the safe assumption in every direction.
Declaring HPOS Compatibility
add_action( 'before_woocommerce_init', function() {
if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
'custom_order_tables', __FILE__, true
);
}
});
HPOS-Compatible Code
- DO: Use
$order->get_meta(), $order->update_meta_data(), $order->save()
- DO: Use
wc_get_orders() with proper args for querying
- DON'T: Use
get_post_meta(), update_post_meta() on orders — with sync-on-read off, these writes are simply lost
- DON'T: Use
WP_Query to query orders directly
- DON'T: Assume
$order->get_id() is a wp_posts ID
- DON'T: Rely on a legacy write "still working because sync is on" — the default flipped, and it will not flip back
Querying
wc_get_orders()
The proper way to query orders (HPOS-compatible):
- Accepts args like
status, customer_id, date_created, meta_key, meta_value
- Returns array of
WC_Order objects
- Under the hood, delegates to the active order data store
wc_get_products()
Query products — delegates to WC_Product_Query:
type, status, sku, category, tag, price, meta_key, etc.
- Returns array of
WC_Product objects
Best Practices
- Always use CRUD getters/setters, never access
$data directly
- Always call
save() after modifying an object
- Use
'edit' context for admin forms, 'view' context for frontend display
- Use
wc_get_orders() / wc_get_products() for queries, not WP_Query
- Declare HPOS compatibility in every extension
- Test with HPOS authoritative mode enabled
Fetch the WooCommerce CRUD and HPOS documentation for exact method signatures, query parameters, and compatibility requirements before implementing.
1---2name: woo-data-stores3description: Work with WooCommerce CRUD data stores — WC_Product, WC_Order, WC_Customer, WC_Coupon data objects, custom data stores, HPOS migration, and getters/setters. Use when creating or modifying WooCommerce data objects or implementing custom data stores.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/woo-data-stores7---89# WooCommerce CRUD & Data Stores1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.woocommerce.com crud data stores` for CRUD documentation152. Web-search `site:github.com woocommerce woocommerce HPOS` for HPOS architecture163. Fetch `https://github.com/woocommerce/woocommerce/wiki` for architecture decisions1718## CRUD Architecture1920### Data Objects2122WooCommerce's core entities extend `WC_Data`:23- `WC_Product` — products (and subtypes: `WC_Product_Simple`, `WC_Product_Variable`, etc.)24- `WC_Order` — orders (and `WC_Order_Refund`)25- `WC_Customer` — customer profiles26- `WC_Coupon` — discount coupons27- `WC_Shipping_Zone` — shipping zones2829### WC_Data Base Class3031All CRUD objects inherit from `WC_Data`:32- `$data` — array of core properties with defaults33- `$meta_data` — array of `WC_Meta_Data` objects34- `$id` — object ID35- `$object_type` — string identifier (e.g., 'product', 'order')36- `$data_store` — the `WC_Data_Store` instance handling persistence3738### Getters and Setters3940- `get_{prop}( $context = 'view' )` — retrieve a property41 - `'view'` context — runs `woocommerce_{object_type}_get_{prop}` filter (for display)42 - `'edit'` context — returns raw stored value (for forms/admin)43- `set_{prop}( $value )` — set a property (in memory, not persisted until `save()`)44- `save()` — persist to database (calls data store's `create()` or `update()`)45- `delete( $force_delete )` — remove from database4647### Meta Data4849- `get_meta( $key, $single, $context )` — get meta value50- `update_meta_data( $key, $value, $meta_id )` — set meta (in memory)51- `delete_meta_data( $key )` — mark meta for deletion52- `save_meta_data()` — persist meta changes (called automatically by `save()`)5354## Data Stores5556### What Data Stores Do5758Data stores abstract the persistence layer. The CRUD object calls generic methods (`read`, `create`, `update`, `delete`) on its data store, which handles the actual SQL.5960### Built-In Data Stores6162| Object | Data Store | Storage |63|--------|-----------|---------|64| Product | `WC_Product_Data_Store_CPT` | `wp_posts` + `wp_postmeta` |65| Order (legacy) | `WC_Order_Data_Store_CPT` | `wp_posts` + `wp_postmeta` |66| Order (HPOS) | `Automattic\WooCommerce\Internal\DataStores\Orders\OrdersTableDataStore` | `wp_wc_orders` + related tables |67| Customer | `WC_Customer_Data_Store` | `wp_users` + `wp_usermeta` |68| Coupon | `WC_Coupon_Data_Store_CPT` | `wp_posts` + `wp_postmeta` |6970### Custom Data Stores7172You can swap data stores via the `woocommerce_{object}_data_store` filter:731. Implement `WC_Object_Data_Store_Interface` (or extend an existing data store)742. Implement methods: `create()`, `read()`, `update()`, `delete()`, `read_meta()`, `update_meta()`, `delete_meta()`753. Filter: `add_filter( 'woocommerce_product_data_store', function() { return 'My_Custom_Store'; } )`7677## HPOS (High-Performance Order Storage)7879### What Changed8081HPOS moves order data from `wp_posts`/`wp_postmeta` to dedicated tables:82- **`wp_wc_orders`** — core order fields (status, currency, total, customer_id, dates)83- **`wp_wc_orders_meta`** — order meta84- **`wp_wc_order_addresses`** — billing/shipping addresses85- **`wp_wc_order_operational_data`** — internal operational data8687### Why HPOS8889- Massive performance improvement for stores with many orders90- Orders no longer pollute the `wp_posts` table91- Dedicated indexes for order queries92- Cleaner separation of concerns9394### Compatibility Modes9596- **Sync enabled** — both posts and custom tables are written (transition period)97- **Authoritative: Custom tables** — custom tables are the source of truth98- **Authoritative: Posts** — legacy mode, posts are source of truth99100### Sync-on-read is off by default101102**This is the failure mode to design against.** WooCommerce disabled HPOS *sync on read* by default in the 10.7 release cycle. Code that writes order data straight into `wp_postmeta` and expects it to appear in HPOS **now fails silently** — no error, no warning, just data that is never read back.103104The practical consequence: legacy order writes are not merely discouraged any more, they are broken. Auditing a plugin for direct `wp_postmeta` order writes is no longer a tidiness exercise, it is a correctness fix.105106Confirm the current default and the exact release in the live docs — fetch `https://developer.woocommerce.com/docs/features/orders/high-performance-order-storage/` — but write code as though sync is off regardless of version. It is the safe assumption in every direction.107108### Declaring HPOS Compatibility109110```php111add_action( 'before_woocommerce_init', function() {112 if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {113 \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(114 'custom_order_tables', __FILE__, true115 );116 }117});118```119120### HPOS-Compatible Code121122- **DO**: Use `$order->get_meta()`, `$order->update_meta_data()`, `$order->save()`123- **DO**: Use `wc_get_orders()` with proper args for querying124- **DON'T**: Use `get_post_meta()`, `update_post_meta()` on orders — with sync-on-read off, these writes are simply lost125- **DON'T**: Use `WP_Query` to query orders directly126- **DON'T**: Assume `$order->get_id()` is a `wp_posts` ID127- **DON'T**: Rely on a legacy write "still working because sync is on" — the default flipped, and it will not flip back128129## Querying130131### wc_get_orders()132133The proper way to query orders (HPOS-compatible):134- Accepts args like `status`, `customer_id`, `date_created`, `meta_key`, `meta_value`135- Returns array of `WC_Order` objects136- Under the hood, delegates to the active order data store137138### wc_get_products()139140Query products — delegates to `WC_Product_Query`:141- `type`, `status`, `sku`, `category`, `tag`, `price`, `meta_key`, etc.142- Returns array of `WC_Product` objects143144## Best Practices145146- Always use CRUD getters/setters, never access `$data` directly147- Always call `save()` after modifying an object148- Use `'edit'` context for admin forms, `'view'` context for frontend display149- Use `wc_get_orders()` / `wc_get_products()` for queries, not `WP_Query`150- Declare HPOS compatibility in every extension151- Test with HPOS authoritative mode enabled152153Fetch the WooCommerce CRUD and HPOS documentation for exact method signatures, query parameters, and compatibility requirements before implementing.