Replace the store's geo settings
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
REPLACES the whole settings row, and every field is required for that reason. An omitted enabled would decode to false and switch geolocation off for the entire store, so a client editing one field through a body that dropped the others would take the merchant's international routing down and read a 200 back. Read /api/v1/geo-settings and send every field. A store that has never configured geo has no row; this creates it. There is no DELETE, because removing the row restores these defaults rather than turning the feature off, which enabled false already does.
The updated_at you last read. Required, because the settings are a singleton written by this route AND by the merchant's dashboard: a write naming no version silently reverts whatever moved under it and answers 200 to both parties. A mismatch is 409 settings_modified. null asserts that this store has no settings row yet, which is the only way a first write can name a version that does not exist, and it is refused once a row does exist.
The master switch. false means the storefront skips geo entirely and no rule fires, whatever an individual rule's own enabled says.
What happens for a shopper no rule matched. The destructive pair (redirect_url, block) is refused here even on a plan that allows them on an individual rule: a default applies to every unmatched visitor in the world, including the merchant's domestic shoppers and every crawler.
switch_market, banner, popup Emit hreflang alternates for the merchant's markets. An SEO switch, not a routing one.
How long the storefront honours a shopper's own market choice before suggesting again. 0 means do not remember it.
0 <= x <= 3650Response
Success
