Sync a store that uses Arabic, Persian, or Chinese attributes through the REST API and you learn the encoding black box the hard way. WooCommerce REST API special characters have been a coin toss for years. You post the JSON, the variation gets created, and then the attributes come back either missing or looking like a mangled URL string.
WooCommerce 10.5 finally deals with two long-standing bugs that left Unicode data undecoded during variation creation. I have watched this break headless builds where the front end was sending perfectly valid UTF-8 and the back-end save still choked on it.
The problem: attribute names vs. values
The API was never consistent about non-ASCII characters, and it failed in two separate places:
- Attribute names (PR #61939): a slug or name holding non-ASCII characters, common in Farsi and Arabic, would not match during the variation lookup.
- Attribute values (PR #62562): option values were not decoded, so the raw encoded string never matched the database term and the variation ended up disconnected from its global attribute.
That is a data integrity problem, not a display one. When a decoding mismatch stops the API from matching a term, it either creates a new term or drops the attribute assignment, which leaves the variation orphaned.
Impact on WooCommerce REST API special characters
The fix lands on the POST and PUT endpoints for product variations. Any integration hitting /wp-json/wc/v3/products/{id}/variations with non-English character sets should get noticeably more reliable.
On one project we wrapped the API just to run rawurldecode() over every incoming attribute value before it reached the woocommerce_rest_insert_product_variation hook, purely to keep the site standing. On 10.5, that kind of patch should come back out.
How to test the fix (WP-CLI or cURL)
On a beta or dev branch of 10.5 you can check this with one cURL request. Here is a variation payload with Persian characters that would previously have failed to map:
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 the fix, the “آبی” (Blue) option might have been stored as an encoded mess or failed to link to the existing term ID. In 10.5 the API handles the decoding before the request reaches the CRUD controllers.
Variation creation can also be a bottleneck on large catalogs, which I went into in my guide to optimizing WooCommerce REST API performance.
Audit your workarounds
If you have been at this a while, there is probably custom logic in your functions.php or a small plugin that “fixes” WooCommerce REST API special characters. Go read it again. Code that decodes strings WooCommerce now decodes on its own gives you double decoding, which mangles the characters all over again.
Start with any use of the woocommerce_rest_pre_insert_product_variation filter where you touch attribute values on the $request object.
If WooCommerce REST API special characters are eating your dev hours, I can take it on. I have been working with WordPress since the 4.x days.
Where 10.5 leaves multilingual stores
For stores running non-English attributes, 10.5 is the release where the endpoints finally behave the way the official REST API documentation already describes them. For the changes just before this one, I broke down the WooCommerce 10.4 API boost.
