RECIPE: Change a Site's Regional Properties via Site Properties API

Goal

Update a Wix site's regional properties — payment currency, time zone, or primary language — programmatically.

When to use

• You need to switch a site's store/payment currency (for example, from USD to EUR).
• You need to change a site's time zone or primary language.
• You want to automate regional/business setup for sites.

Important notes before you start

• These fields are part of Site Properties (often shown in the dashboard under regional/business info).
• A successful update increments the Site Properties version.
• Use a field mask (fields.paths) to indicate which fields you're updating.
• Field mask paths are top-level property names. The read response also contains a locale object, but it is not the write surface — see Gotchas.

Step 1 — (Optional) Read current site properties version

This is useful to understand the current snapshot version and other regional fields.

Step 2 — Update the properties you need

Use the PATCH /site-properties/v4/properties endpoint: put the new values under properties and name each one in a fields.paths mask.

Time zone, same shape:

To update several properties at once, include each one in properties and name each in paths:

Expected response

A successful call returns only the updated Site Properties snapshot version — it does not echo the properties back:

To confirm the new value, re-read with the Step 1 GET.

Gotchas & troubleshooting

• Always send a field mask: omitting fields.paths fails with 400 and "Illegal request - No updates on request body".
• Do not nest the mask path under locale. The GET response contains a locale object (languageCode, country), which makes a path like locale.timezone look plausible — it is rejected with 400 and "Illegal request - Unknown field in field mask - locale.timezone". Time zone and language are the top-level timeZone and language fields.
• locale.languageCode is a read-only projection and can differ from the top-level language value. Set language; read language back to verify.
• Currency must be a 3-letter ISO-4217 code (for example, USD, CAD, EUR, GBP).
• There is no separate per-field endpoint for currency, time zone, or language — all three go through this one call.

Related APIs

• Site Properties API: REST
• Get Site Properties (full read shape): REST
• Stores Currency Converter (conversion utilities, not for setting the site currency):
  • POST https://www.wixapis.com/currency_converter/v1/currencies/amounts/{from}/convert/{to}