Replace a geo rule

curl --request PUT \
  --url https://api.mercemur.com/api/v1/geo-rules/{geoRuleId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "enabled": true,
  "priority": 123,
  "match_values": [
    "<string>"
  ],
  "target_region_id": "<string>",
  "target_url": "<string>",
  "target_locale": "<string>",
  "display": {}
}
'

const options = {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    enabled: true,
    priority: 123,
    match_values: ['<string>'],
    target_region_id: '<string>',
    target_url: '<string>',
    target_locale: '<string>',
    display: {}
  })
};

fetch('https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}"

payload = {
    "name": "<string>",
    "enabled": True,
    "priority": 123,
    "match_values": ["<string>"],
    "target_region_id": "<string>",
    "target_url": "<string>",
    "target_locale": "<string>",
    "display": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"enabled\": true,\n  \"priority\": 123,\n  \"match_values\": [\n    \"<string>\"\n  ],\n  \"target_region_id\": \"<string>\",\n  \"target_url\": \"<string>\",\n  \"target_locale\": \"<string>\",\n  \"display\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'enabled' => true,
    'priority' => 123,
    'match_values' => [
        '<string>'
    ],
    'target_region_id' => '<string>',
    'target_url' => '<string>',
    'target_locale' => '<string>',
    'display' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "action": "<string>",
    "created_at": "<string>",
    "display": {
      "dismissible": true,
      "mode": "<string>",
      "position": "<string>"
    },
    "enabled": true,
    "id": "<string>",
    "match_type": "<string>",
    "match_values": [
      "<string>"
    ],
    "name": "<string>",
    "priority": 123,
    "redirect_status": 123,
    "target_locale": "<string>",
    "target_region_id": "<string>",
    "target_url": null,
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

PUT

api

geo-rules

{geoRuleId}

Replace a geo rule

curl --request PUT \
  --url https://api.mercemur.com/api/v1/geo-rules/{geoRuleId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "enabled": true,
  "priority": 123,
  "match_values": [
    "<string>"
  ],
  "target_region_id": "<string>",
  "target_url": "<string>",
  "target_locale": "<string>",
  "display": {}
}
'

const options = {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    enabled: true,
    priority: 123,
    match_values: ['<string>'],
    target_region_id: '<string>',
    target_url: '<string>',
    target_locale: '<string>',
    display: {}
  })
};

fetch('https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}"

payload = {
    "name": "<string>",
    "enabled": True,
    "priority": 123,
    "match_values": ["<string>"],
    "target_region_id": "<string>",
    "target_url": "<string>",
    "target_locale": "<string>",
    "display": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"enabled\": true,\n  \"priority\": 123,\n  \"match_values\": [\n    \"<string>\"\n  ],\n  \"target_region_id\": \"<string>\",\n  \"target_url\": \"<string>\",\n  \"target_locale\": \"<string>\",\n  \"display\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/geo-rules/{geoRuleId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'enabled' => true,
    'priority' => 123,
    'match_values' => [
        '<string>'
    ],
    'target_region_id' => '<string>',
    'target_url' => '<string>',
    'target_locale' => '<string>',
    'display' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "action": "<string>",
    "created_at": "<string>",
    "display": {
      "dismissible": true,
      "mode": "<string>",
      "position": "<string>"
    },
    "enabled": true,
    "id": "<string>",
    "match_type": "<string>",
    "match_values": [
      "<string>"
    ],
    "name": "<string>",
    "priority": 123,
    "redirect_status": 123,
    "target_locale": "<string>",
    "target_region_id": "<string>",
    "target_url": null,
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

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.

Path Parameters

geoRuleId

string

required

Body

application/json

A FULL REPLACE on both routes, which is why the create and the replace take the same body and why PUT is the method rather than PATCH. An omitted optional key is CLEARED rather than carried over, so read the rule and send back what you want it to end up with. THE SIX REQUIRED FIELDS INCLUDE enabled AND priority, which look defaultable and are not: omitted, they decode to false and 0, and the first silently stops a live rule firing while the second promotes it ahead of every other rule in the store. Neither raises an error and neither is visible until an international shopper sees the wrong storefront, so both are refused when absent. 402 rather than 403 when the merchant's PLAN refuses: the store's rule cap, and the redirect_url and block actions. That is not a scope you can ask for; only the merchant can change it.

name

string

required

Unique per store, which makes it a stable handle a migration tool can re-run against. A duplicate is 409 rule_exists rather than a second rule.

enabled

boolean

required

false leaves the rule stored and stops the storefront evaluating it. This is the REVERSIBLE form of removing a rule, and it is reachable on write_geo alone, unlike the DELETE.

priority

integer

required

Evaluation order, LOWEST FIRST, and the first matching rule wins. Not unique and not a position in the list: the list is paged by creation time precisely because re-prioritising one rule would otherwise shift every rule after it across a page boundary.

match_type

enum<string>

required

Decides how match_values is read.

Available options:

country,

ip_cidr

match_values

string[]

required

Two-letter ISO 3166-1 alpha-2 country codes for a country rule, normalised to uppercase, or CIDR blocks for an ip_cidr one. At least one; an empty array is refused rather than stored as a rule that matches nothing.

Required array length: 1 - 250 elements

action

enum<string>

required

switch_market needs target_region_id. redirect_url needs an absolute http(s) target_url. redirect_url and block require a paid plan and are refused 402 on a plan without it, rather than stored and silently ignored.

Available options:

switch_market,

redirect_url,

banner,

popup,

block

target_region_id

string | null

The market a switch_market rule moves the shopper into. A region of this store, listed at /api/v1/regions; a region id from anywhere else is 400 invalid_region rather than 404. Null or omitted on every other action.

target_url

string | null

Where a redirect_url rule sends the shopper. Absolute, http or https.

target_locale

string | null

The language a switch_market rule also sets, like en or en-CA. Omit it to leave the shopper's language alone.

redirect_status

enum<integer>

Only meaningful on a redirect_url rule. Omit it for 302. Anything other than 301 or 302 is a 400 rather than a silently corrected redirect.

Available options:

301,

302

display

object

The presentation document for the banner, popup or block surface: colours, position, dismissible, and the switch_market mode. It is sent and served as the stored document rather than as named fields, so a read is round-trippable through this replace; a client that dropped it would blank the merchant's styling and the banner would go plain with nothing to say why. Colours must be strict hex and position must be top or bottom, because both reach inline styles on the storefront. Omitted means {} and therefore the storefront's own defaults.

Response

Success

data

object

Show child attributes

Overview

Endpoints

Replace a geo rule

Authorizations

Headers

Path Parameters

Body

Response