Merchants and addresses
A merchant is a customer account of your shipping company: a store that ships through you. Shipments are booked for a merchant, priced with that merchant's rate card, and sent from one of the merchant's saved pickup addresses. Webhook subscriptions belong to a merchant too.
Scopes: merchants:read to list and read; merchants:write to create and change. Writing does not include reading. A merchant login can read only its own merchant record and addresses and cannot write.
The API exposes the business data you need and deliberately not banking, commission, API key or pricing details of a merchant.
GET /merchants is paginated and ordered by name. Filters: search (matched against name, contact person, phone and email) and isActive. GET /merchants/{id} returns one merchant with its primary address.
curl -G "https://api.goldrock.live/api/public/v1/merchants" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'search=noor' \
--data-urlencode 'isActive=true'const params = new URLSearchParams({
"search": "noor",
"isActive": "true"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/merchants?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants?' . http_build_query([
'search' => 'noor',
'isActive' => 'true',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/merchants",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"search": "noor",
"isActive": "true",
},
timeout=30,
)
print(response.status_code, response.json()){
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Noor Electronics",
"contactName": "Omar Hassan",
"contactPhone": "0501234567",
"contactEmail": "orders@noor-electronics.example",
"isActive": true,
"createdAt": "2026-01-10T08:00:00Z",
"primaryAddress": {
"id": "9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42",
"label": "Main warehouse",
"contactName": "Omar Hassan",
"contactPhone": "0501234567",
"country": {
"id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
"nameAr": "المملكة العربية السعودية",
"nameEn": "Saudi Arabia"
},
"city": {
"id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
"nameAr": "الرياض",
"nameEn": "Riyadh"
},
"district": {
"id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
"nameAr": "العليا",
"nameEn": "Al Olaya"
},
"addressLine": "King Fahd Road, Warehouse 4",
"shortAddress": "RNBA6769",
"latitude": null,
"longitude": null,
"isPrimary": true
}
}POST /merchants uses the dashboard's rules:
name,contactEmailandcommercialRegNo(commercial registration or freelance licence number) are required.contactEmailis unique across the platform.taxId(VAT number) is required unlessnotVatRegisteredistrue.address(the primary pickup address) is required. Country, city and district are matched by name and nothing is created (Places by name). A Saudi address needsshortAddress.- Unlike the dashboard, no merchant login and no e-mail are created. A merchant login is created in the dashboard.
curl -X POST "https://api.goldrock.live/api/public/v1/merchants" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: merchant-1010123456" \
-d '{
"name": "Noor Electronics",
"contactName": "Omar Hassan",
"contactPhone": "0501234567",
"contactEmail": "orders@noor-electronics.example",
"commercialRegNo": "1010123456",
"taxId": "300123456700003",
"notVatRegistered": false,
"address": {
"label": "Main warehouse",
"contactPhone": "0501234567",
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Warehouse 4",
"shortAddress": "RNBA6769"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "merchant-1010123456"
},
body: JSON.stringify({
"name": "Noor Electronics",
"contactName": "Omar Hassan",
"contactPhone": "0501234567",
"contactEmail": "orders@noor-electronics.example",
"commercialRegNo": "1010123456",
"taxId": "300123456700003",
"notVatRegistered": false,
"address": {
"label": "Main warehouse",
"contactPhone": "0501234567",
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Warehouse 4",
"shortAddress": "RNBA6769"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: merchant-1010123456',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Noor Electronics',
'contactName' => 'Omar Hassan',
'contactPhone' => '0501234567',
'contactEmail' => 'orders@noor-electronics.example',
'commercialRegNo' => '1010123456',
'taxId' => '300123456700003',
'notVatRegistered' => false,
'address' => [
'label' => 'Main warehouse',
'contactPhone' => '0501234567',
'country' => 'SA',
'city' => 'Riyadh',
'district' => 'Al Olaya',
'addressLine' => 'King Fahd Road, Warehouse 4',
'shortAddress' => 'RNBA6769',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "merchant-1010123456",
},
json={
"name": "Noor Electronics",
"contactName": "Omar Hassan",
"contactPhone": "0501234567",
"contactEmail": "orders@noor-electronics.example",
"commercialRegNo": "1010123456",
"taxId": "300123456700003",
"notVatRegistered": False,
"address": {
"label": "Main warehouse",
"contactPhone": "0501234567",
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Warehouse 4",
"shortAddress": "RNBA6769",
},
},
timeout=30,
)
print(response.status_code, response.json())Data that matches another merchant on the platform is refused with 409: merchant.email_taken_format when the e-mail already belongs to a merchant, and merchant.same_merchant_format when a merchant with the same name and commercial registration already exists. When the data only looks similar (the same registration or VAT number, or a similar name), the answer is 409 merchant.possible_duplicate. If you are sure this is a different store, send the same request with confirmPossibleDuplicate: true.
Send an Idempotency-Key so a retry cannot create the merchant twice.
PUT /merchants/{id} changes only the fields you send: name, contactName, contactPhone, contactEmail. Registration numbers, pricing and banking are untouched.
curl -X PUT "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"contactName": "Omar Hassan",
"contactPhone": "0509876543"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6", {
method: "PUT",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"contactName": "Omar Hassan",
"contactPhone": "0509876543"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'contactName' => 'Omar Hassan',
'contactPhone' => '0509876543',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"PUT",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"contactName": "Omar Hassan",
"contactPhone": "0509876543",
},
timeout=30,
)
print(response.status_code, response.json())A merchant has one or more saved pickup addresses. The primary one is the default pickup of the merchant's shipments and the destination of its returns. The first address is always primary.
| Operation | Notes |
|---|---|
GET /merchants/{id}/addresses |
The primary address first |
POST /merchants/{id}/addresses |
Add an address. makePrimary: true makes it primary. Supports Idempotency-Key |
PUT /merchants/{id}/addresses/{addressId} |
Replaces the whole address; the primary flag is unchanged |
POST /merchants/{id}/addresses/{addressId}/primary |
Make this address the primary one |
DELETE /merchants/{id}/addresses/{addressId} |
The only address cannot be deleted. Deleting the primary promotes the oldest remaining one |
An address needs label (up to 100 characters), contactPhone, city, district and addressLine (up to 500 characters). contactName defaults to the merchant name. Names that do not match fail with geo_* errors whose details.field is address.
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"label": "Jeddah branch",
"contactPhone": "0501234567",
"country": "SA",
"city": "جده",
"district": "حي الروضة",
"addressLine": "Tahlia Street, Shop 9",
"shortAddress": "JEDA2345",
"makePrimary": false
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"label": "Jeddah branch",
"contactPhone": "0501234567",
"country": "SA",
"city": "جده",
"district": "حي الروضة",
"addressLine": "Tahlia Street, Shop 9",
"shortAddress": "JEDA2345",
"makePrimary": false
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Jeddah branch',
'contactPhone' => '0501234567',
'country' => 'SA',
'city' => 'جده',
'district' => 'حي الروضة',
'addressLine' => 'Tahlia Street, Shop 9',
'shortAddress' => 'JEDA2345',
'makePrimary' => false,
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"label": "Jeddah branch",
"contactPhone": "0501234567",
"country": "SA",
"city": "جده",
"district": "حي الروضة",
"addressLine": "Tahlia Street, Shop 9",
"shortAddress": "JEDA2345",
"makePrimary": False,
},
timeout=30,
)
print(response.status_code, response.json())curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())| Code | Cause |
|---|---|
merchant.not_found |
Wrong id, or a merchant login asked for another merchant |
merchant.address_not_found |
The address id does not belong to this merchant |
merchant.possible_duplicate, merchant.email_taken_format, merchant.same_merchant_format |
Duplicate detection, see above |
validation_failed |
A required field is missing or malformed |
geo_* |
A place name did not match |