If you have ever tried to sync a store that uses Arabic, Persian, or Chinese attributes via the REST API, you know exactly how frustrating the encoding “black box” can be. For years, dealing with WooCommerce REST API special characters has been a game of Russian roulette. You ship the JSON, the variation gets created, but the attributes are either missing or look like a broken URL string.
WooCommerce 10.5 finally addresses two specific, long-standing bugs that were essentially failing to decode Unicode data properly during variation creation. I’ve seen this break many headless builds where the front-end was sending perfectly valid UTF-8, only for the API to choke on the back-end save.
The Problem: Attribute Names vs. Values
The core of the issue was a lack of consistency in how the API handled non-ASCII characters. Specifically, there were two distinct failure points:
- Attribute Names (PR #61939): Previously, if your attribute slug or name contained non-ASCII characters (common in Farsi or Arabic), the API wouldn’t match them correctly during the variation lookup.
- Attribute Values (PR #62562): Option values weren’t being properly decoded. This resulted in variations being “disconnected” from their global attributes because the raw encoded string didn’t match the database term.
This wasn’t just a display bug; it was a data integrity issue. When the API fails to match a term because of a decoding mismatch, it often creates a new term or simply ignores the attribute assignment, leaving the variation orphaned.
Impact on WooCommerce REST API Special Characters Handling
This fix primarily impacts the POST and PUT endpoints for product variations. Specifically, any integration hitting /wp-json/wc/v3/products/{id}/variations with non-English character sets should see immediate improvements in reliability.
I recall a project where we had to write a custom wrapper to rawurldecode() every incoming attribute value before it hit the woocommerce_rest_insert_product_variation hook just to keep the site from breaking. With 10.5, those types of “dirty” workarounds should be refactored or removed.
How to Test the Fix (WP-CLI or cURL)
If you are running a beta or a dev branch of 10.5, you can verify this using a simple cURL request. Here is an example of a variation payload using Persian characters that previously might have failed to map correctly:
curl -X POST https://example.com/wp-json/wc/v3/products/123/variations \
-u consumer_key:consumer_secret \
-H \"Content-Type: application/json\" \
-d '{
\"attributes\": [
{
\"id\": 1,
\"name\": \"رنگ\",
\"option\": \"آبی\"
}
]
}'Before this fix, the \”آبی\” (Blue) option might have been saved as an encoded mess or failed to link to the existing term ID. In 10.5, the API now handles the decoding logic internally before reaching the CRUD controllers.
While you’re at it, you might want to check out my guide on optimizing WooCommerce REST API performance, as variation creation can be a bottleneck for large catalogs.
Audit Your Workarounds
If you have been in the game long enough, you probably have some custom logic in your functions.php or a custom plugin to “fix” WooCommerce REST API special characters. You need to review these. If your code is manually decoding strings that WooCommerce now decodes automatically, you risk “double decoding,” which can mangle characters further.
Specifically, look for any usage of the woocommerce_rest_pre_insert_product_variation filter where you might be manipulating the $request object’s attribute values.
Look, if this WooCommerce REST API special characters stuff is eating up your dev hours, let me handle it. I’ve been wrestling with WordPress since the 4.x days.
Takeaway for 10.5
The 10.5 update is a win for internationalization. It makes the official REST API documentation more accurate because the endpoints will finally behave as expected. For further reading on recent Woo shifts, check my breakdown of the WooCommerce 10.4 API boost.
