Variables REST API - Able to Update Default Mode Value but Failing for Non-Default Mode on Bound String Variable
Hi Figma Team / Community,
I'm experimenting with the Variables REST API (POST /v1/files/:file_key/variables) and trying to understand the behavior when updating string variables across different modes.
My Setup
Variable Collection
{
"name": "Localization",
"collectionId": "VariableCollectionId:40000196:4269"
}
Modes
| Mode Name | Mode ID |
|---|---|
| EN | 40000196:0 |
| DE | 40000196:1 |
| Mode | 40000200:0 |
EN is the default mode for this collection.
Variables
Variable 1 - Bound Variable
{
"variableId": "VariableID:40000200:3754",
"name": "suite",
"type": "STRING"
}
Current values:
{
"EN": "ABC_EN",
"DE": "123",
"Mode": "Mode"
}
This variable is bound to text content in the design.
Variable 2 - Unbound Variable
{
"variableId": "VariableID:40000221:57715",
"name": "New_Variable_Str",
"type": "STRING"
}
Current values:
{
"EN": "ABC_EN",
"DE": "ABC_DE",
"Mode": ""
}
This variable is currently not bound to any node.
What Works
I'm able to update the EN mode value for the bound variable (suite) using the following payload:
{
"variableModeValues": [
{
"variableId": "VariableID:40000200:3754",
"modeId": "40000196:0",
"value": "ABC_EN"
}
]
}
Response:
{
"status": 200,
"error": false
}
The value is updated successfully.
What Fails
When I try to update the DE mode value of the same variable:
{
"variableModeValues": [
{
"variableId": "VariableID:40000200:3754",
"modeId": "40000196:1",
"value": "ABC_DE"
}
]
}
I get:
{
"status": 400,
"error": true,
"message": "Some node properties bound to the following variables could not be updated: VariableID:40000200:3754"
}
Observation
So far, my observations are:
| Scenario | Result |
|---|---|
| Bound variable + EN mode (default mode) | ✅ Works |
| Bound variable + DE mode (non-default mode) | ❌ Fails |
| Unbound variable + DE mode | ✅ Works |
This makes me wonder whether there is a restriction related to:
- Updating non-default mode values for variables that are currently bound to nodes.
- Updating localization values on bound text variables through the REST API.
- Whether this behavior is expected/documented or a limitation of the current Variables API implementation.
Questions
- Is updating non-default mode values of bound variables via
variableModeValuescurrently unsupported? - Is there any documented guidance on updating localized string variables through the REST API when they are already bound to text nodes?
- Has anyone successfully used the Variables REST API to update translation/localization variables across multiple modes (EN/DE/FR/etc.) while those variables remain bound in the design?
- Is the Plugin API currently the only supported approach for this scenario?
Any clarification or workaround would be greatly appreciated.
Thanks!