Add a retail location to the store directory

curl --request POST \
  --url https://api.mercemur.com/api/v1/retail-locations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "slug": "<string>",
  "name": "<string>",
  "address_line_1": "<string>",
  "city": "<string>",
  "country_code": "<string>",
  "address_line_2": "<string>",
  "region": "<string>",
  "postal_code": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "website_url": "<string>",
  "hours": {},
  "custom_fields": {},
  "tags": [
    "<string>"
  ],
  "is_active": true,
  "position": 123
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    slug: '<string>',
    name: '<string>',
    address_line_1: '<string>',
    city: '<string>',
    country_code: '<string>',
    address_line_2: '<string>',
    region: '<string>',
    postal_code: '<string>',
    phone: '<string>',
    email: '<string>',
    website_url: '<string>',
    hours: {},
    custom_fields: {},
    tags: ['<string>'],
    is_active: true,
    position: 123
  })
};

fetch('https://api.mercemur.com/api/v1/retail-locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/retail-locations"

payload = {
    "slug": "<string>",
    "name": "<string>",
    "address_line_1": "<string>",
    "city": "<string>",
    "country_code": "<string>",
    "address_line_2": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "email": "<string>",
    "website_url": "<string>",
    "hours": {},
    "custom_fields": {},
    "tags": ["<string>"],
    "is_active": True,
    "position": 123
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(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/retail-locations"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"name\": \"<string>\",\n  \"address_line_1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"address_line_2\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\",\n  \"website_url\": \"<string>\",\n  \"hours\": {},\n  \"custom_fields\": {},\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"is_active\": true,\n  \"position\": 123\n}")

	req, _ := http.NewRequest("POST", 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/retail-locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'name' => '<string>',
    'address_line_1' => '<string>',
    'city' => '<string>',
    'country_code' => '<string>',
    'address_line_2' => '<string>',
    'region' => '<string>',
    'postal_code' => '<string>',
    'phone' => '<string>',
    'email' => '<string>',
    'website_url' => '<string>',
    'hours' => [
        
    ],
    'custom_fields' => [
        
    ],
    'tags' => [
        '<string>'
    ],
    'is_active' => true,
    'position' => 123
  ]),
  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": {
    "address_line_1": "<string>",
    "address_line_2": "<string>",
    "city": "<string>",
    "country_code": "<string>",
    "created_at": "<string>",
    "custom_fields": {
      "parking": "<string>"
    },
    "email": "<string>",
    "hours": {
      "monday": "<string>"
    },
    "id": "<string>",
    "is_active": true,
    "name": "<string>",
    "phone": "<string>",
    "position": 123,
    "postal_code": "<string>",
    "region": "<string>",
    "slug": "<string>",
    "tags": [
      "<string>"
    ],
    "updated_at": "<string>",
    "website_url": "<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>"
  }
}

POST

api

retail-locations

Add a retail location to the store directory

curl --request POST \
  --url https://api.mercemur.com/api/v1/retail-locations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "slug": "<string>",
  "name": "<string>",
  "address_line_1": "<string>",
  "city": "<string>",
  "country_code": "<string>",
  "address_line_2": "<string>",
  "region": "<string>",
  "postal_code": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "website_url": "<string>",
  "hours": {},
  "custom_fields": {},
  "tags": [
    "<string>"
  ],
  "is_active": true,
  "position": 123
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    slug: '<string>',
    name: '<string>',
    address_line_1: '<string>',
    city: '<string>',
    country_code: '<string>',
    address_line_2: '<string>',
    region: '<string>',
    postal_code: '<string>',
    phone: '<string>',
    email: '<string>',
    website_url: '<string>',
    hours: {},
    custom_fields: {},
    tags: ['<string>'],
    is_active: true,
    position: 123
  })
};

fetch('https://api.mercemur.com/api/v1/retail-locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/retail-locations"

payload = {
    "slug": "<string>",
    "name": "<string>",
    "address_line_1": "<string>",
    "city": "<string>",
    "country_code": "<string>",
    "address_line_2": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "email": "<string>",
    "website_url": "<string>",
    "hours": {},
    "custom_fields": {},
    "tags": ["<string>"],
    "is_active": True,
    "position": 123
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(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/retail-locations"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"name\": \"<string>\",\n  \"address_line_1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"address_line_2\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\",\n  \"website_url\": \"<string>\",\n  \"hours\": {},\n  \"custom_fields\": {},\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"is_active\": true,\n  \"position\": 123\n}")

	req, _ := http.NewRequest("POST", 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/retail-locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'name' => '<string>',
    'address_line_1' => '<string>',
    'city' => '<string>',
    'country_code' => '<string>',
    'address_line_2' => '<string>',
    'region' => '<string>',
    'postal_code' => '<string>',
    'phone' => '<string>',
    'email' => '<string>',
    'website_url' => '<string>',
    'hours' => [
        
    ],
    'custom_fields' => [
        
    ],
    'tags' => [
        '<string>'
    ],
    'is_active' => true,
    'position' => 123
  ]),
  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": {
    "address_line_1": "<string>",
    "address_line_2": "<string>",
    "city": "<string>",
    "country_code": "<string>",
    "created_at": "<string>",
    "custom_fields": {
      "parking": "<string>"
    },
    "email": "<string>",
    "hours": {
      "monday": "<string>"
    },
    "id": "<string>",
    "is_active": true,
    "name": "<string>",
    "phone": "<string>",
    "position": 123,
    "postal_code": "<string>",
    "region": "<string>",
    "slug": "<string>",
    "tags": [
      "<string>"
    ],
    "updated_at": "<string>",
    "website_url": "<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.

Body

application/json

The directory row only. The four geo fields (latitude, longitude, geocode_status, geocoded_at) are refused BY NAME rather than ignored: they record where THIS PLATFORM resolved the address to and when, so a supplied one would assert a geocode that never ran and nothing downstream could tell it from a real result. The map pin and the store-wide locator settings are refused for the same reason they are not published: they configure a rendered widget rather than describe a shopfront. The slug is unique per store, and a deleted location keeps holding its slug, so a retry past the idempotency window answers 409 slug_taken instead of minting a second shopfront at the same address.

slug

string

required

The storefront URL segment, lowercase kebab-case. Required rather than derived from the name: this API does not invent an identifier a merchant will see in a URL. It is MUTABLE, which is why the detail route keys on the id.

name

string

required

address_line_1

string

required

city

string

required

country_code

string

required

Two letters. Stored and served EXACTLY as sent, with no case normalisation anywhere in the write path.

address_line_2

string | null

region

string | null

postal_code

string | null

phone

string | null

website_url

string | null

hours

object

The merchant's opening-hours map, deliberately opaque: no schema, no canonical key set, no validation. It publishes exactly what the merchant typed rather than pretending to a structure the write path never enforced. A consumer needing schema.org openingHours maps it.

custom_fields

object

A free-form merchant-authored bag. It is safe to publish only while every writer is merchant input, so internal state belongs in a new field and never in here.

Response

Created

data

object

Show child attributes

Overview

Endpoints

Add a retail location to the store directory

Authorizations

Headers

Body

Response