curl --request GET \
--url https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores \
--header 'X-API-Key: <api-key>'import requests
url = "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"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"
}
],
"pagination": {
"has_next": true,
"has_previous": false,
"page": 1,
"page_size": 25,
"total_count": 342,
"total_pages": 14
}
}{
"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"
}List a retailer's physical stores
Every physical store on file for one retailer, paginated.
Unfiltered by default, retired stores included. The count returned here is therefore the same population the store upsert reports as existing_stores, which is the point: after an import whose outcome is unknown, this is how you ask what the catalog holds without re-running a dry-run import to find out. Pass is_active=true for only the live ones.
Ordered by name, then by id so the ordering is total and paging cannot skip or repeat a store whose name it shares with another.
Reading a canonical (Closient-curated) retailer’s stores needs only an authenticated caller — those rows are already public on the Directory pages. An organization-private retailer requires view access on the organization that owns it, and a credential scoped to a different organization gets 404 rather than 403, so the API never confirms that another organization’s retailer exists.
curl --request GET \
--url https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores \
--header 'X-API-Key: <api-key>'import requests
url = "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/retailers/api/v1/retailers/{retailer_id}/stores")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"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"
}
],
"pagination": {
"has_next": true,
"has_previous": false,
"page": 1,
"page_size": 25,
"total_count": 342,
"total_pages": 14
}
}{
"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 whose stores to list.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Query Parameters
Only stores whose place is in this ISO 3166-1 alpha-2 country. Case-insensitive. A syntactically valid code that is not assigned to any country matches nothing and returns an empty page rather than an error — this filters, it does not validate.
2^[A-Za-z]{2}$Only active (true) or only retired (false) stores. Omit for both.
Page number (1-indexed).
x >= 1Number of items per page (max 100).
1 <= x <= 100Response
OK
Items on the current page, each conforming to the endpoint's item schema. Empty when the result set is empty or page is past the end.
Show child attributes
Show child attributes
Pagination envelope describing position within the full result set.
Show child attributes
Show child attributes
{
"has_next": true,
"has_previous": false,
"page": 1,
"page_size": 25,
"total_count": 342,
"total_pages": 14
}