GROperator

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.

GET /merchants
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'
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, contactEmail and commercialRegNo (commercial registration or freelance licence number) are required. contactEmail is unique across the platform.
  • taxId (VAT number) is required unless notVatRegistered is true.
  • 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 needs shortAddress.
  • Unlike the dashboard, no merchant login and no e-mail are created. A merchant login is created in the dashboard.
POST /merchants
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"
  }
}'

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.

PUT /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6
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"
}'

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.

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses
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
}'
POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary
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"
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