PUT
Replace the store's geo settings

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

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

application/json

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.

expected_updated_at
string | null
required

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.

enabled
boolean
required

The master switch. false means the storefront skips geo entirely and no rule fires, whatever an individual rule's own enabled says.

default_action
enum<string>
required

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.

Available options:
switch_market,
banner,
popup
hreflang_enabled
boolean
required

Emit hreflang alternates for the merchant's markets. An SEO switch, not a routing one.

respect_choice_days
integer
required

How long the storefront honours a shopper's own market choice before suggesting again. 0 means do not remember it.

Required range: 0 <= x <= 3650

Response

Success

data
object