curl --request PATCH \
--url https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": "USD",
"name": "Ulta Beauty - Springfield",
"store_number": "595"
}
'import requests
url = "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}"
payload = {
"currency": "USD",
"name": "Ulta Beauty - Springfield",
"store_number": "595"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({currency: 'USD', name: 'Ulta Beauty - Springfield', store_number: '595'})
};
fetch('https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'currency' => 'USD',
'name' => 'Ulta Beauty - Springfield',
'store_number' => '595'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}"
payload := strings.NewReader("{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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))
}HttpResponse<String> response = Unirest.patch("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}"
response = http.request(request)
puts response.read_body{
"address_line_1": "1250 Main St",
"address_line_2": "",
"city": "Springfield",
"country": "US",
"created": "2026-01-15T10:00:00Z",
"currency": "USD",
"gln": "0078742000008",
"id": "8f4c2a1b6d3e5f7a9c0b2d4e6f",
"is_active": true,
"latitude": 39.7817,
"longitude": -89.6501,
"modified": "2026-02-01T09:30:00Z",
"name": "Ulta Beauty",
"place_id": "a1b2c3d4e5f60718293a4b5c6d",
"postal_code": "62704",
"region": "IL",
"retailer_id": "f47ac10b58cc4372a5670e02b2",
"store_number": "595"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}Update one physical store
Correct a single store’s own columns — name, store number, currency, GLN, active flag. Only the fields present in the body are written.
Address and coordinates are not writable here. They live on the store’s place and carry per-column provenance the reconciling upsert maintains; send an address correction to POST /retailers/{retailer_id}/stores instead, which also re-runs the duplicate matcher against it.
A store_number another store of this retailer already holds returns 409.
Authorization is identical to creating a store for this retailer: an organization-private retailer requires OWNER or MANAGER on the organization that owns it; a canonical (Closient-curated) retailer requires a staff account or the catalog-import service account. Whoever may upsert a store may correct and retire it.
curl --request PATCH \
--url https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": "USD",
"name": "Ulta Beauty - Springfield",
"store_number": "595"
}
'import requests
url = "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}"
payload = {
"currency": "USD",
"name": "Ulta Beauty - Springfield",
"store_number": "595"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({currency: 'USD', name: 'Ulta Beauty - Springfield', store_number: '595'})
};
fetch('https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'currency' => 'USD',
'name' => 'Ulta Beauty - Springfield',
'store_number' => '595'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}"
payload := strings.NewReader("{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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))
}HttpResponse<String> response = Unirest.patch("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores/{store_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\",\n \"name\": \"Ulta Beauty - Springfield\",\n \"store_number\": \"595\"\n}"
response = http.request(request)
puts response.read_body{
"address_line_1": "1250 Main St",
"address_line_2": "",
"city": "Springfield",
"country": "US",
"created": "2026-01-15T10:00:00Z",
"currency": "USD",
"gln": "0078742000008",
"id": "8f4c2a1b6d3e5f7a9c0b2d4e6f",
"is_active": true,
"latitude": 39.7817,
"longitude": -89.6501,
"modified": "2026-02-01T09:30:00Z",
"name": "Ulta Beauty",
"place_id": "a1b2c3d4e5f60718293a4b5c6d",
"postal_code": "62704",
"region": "IL",
"retailer_id": "f47ac10b58cc4372a5670e02b2",
"store_number": "595"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}Authorizations
Path Parameters
Unique identifier of the retailer this store belongs to.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Unique identifier of the store to update.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Body
Fields a PATCH may change on an existing store.
Every field is optional and only the ones present in the request body are written, so a caller correcting one column cannot blank the rest by omission.
The address is not here. Street, city, coordinates and country live on
the store's place and carry per-source provenance — which source wrote each
column, whether it was first-party, and the previous value it superseded.
Only the reconciling upsert maintains that, so address corrections go
through POST /retailers/{retailer_id}/stores, which also re-runs the
duplicate matcher. Repointing the store at a different place is likewise
refused: a place belongs to whichever organization created it, and
accepting an id here would let a store be attached to another
organization's location record.
Store or branch display name.
255The retailer's own key for this store. Unique per retailer when non-empty — a value another store of this retailer already holds is refused with 409, because re-keying one store onto another's number is how two stores become indistinguishable to the upsert matcher.
50GS1 Global Location Number for this store. Must already be registered — this does not mint one, because a GLN is issued by GS1 and a row invented here would be a fabricated identifier in the registry. Send "" to detach the current GLN.
13ISO 4217 code offers at this store are priced in.
3Set false to retire the store (the same effect as DELETE), true to reinstate one. Retailer.is_physical is derived from the presence of active stores, so this is what flips that flag.
Response
OK
One physical store as the catalog holds it.
The retailer-owned columns plus a flattened copy of the store's
locations.Place address, because a caller reconciling its own dataset
against ours needs the address to compare against and should not have to
follow a second identifier into another app's API to get it.
URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Store or branch display name.
The retailer's own key for this store, or the synthesized key the import recorded. Unique within a retailer when non-empty, and the highest-confidence tier the store upsert matches on.
False for a retired store. DELETE clears this flag rather than removing the row, so a deleted store still appears in this list unless you filter it out with is_active=true.
Identifier of the locations.Place this store occupies — the geographic record.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$When this store row was first written.
When this store row last changed.
GS1 Global Location Number identifying this store, when issued.
ISO 4217 code offers at this store are priced in. Empty when unset.
Street address, number and street name.
Apartment, suite, unit or floor.
City, town or locality.
State, province or region.
ZIP, postal code or postcode.
ISO 3166-1 alpha-2 country code of the store.
WGS84 latitude in decimal degrees. Null when uncoordinated.
WGS84 longitude in decimal degrees. Null when uncoordinated.