GROperator

Merchants

Every operation of the LastMile Public API, generated from the OpenAPI document. The reference text is in English in both languages.

GET

/api/public/v1/merchants

#

List merchants

API key + secret, or bearer tokenRequired scope: merchants:read

Ordered by name, paginated. No banking, commission, API key or pricing fields are exposed.

Parameters

NameInTypeDescription
pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Text matched against name, contact person, phone and email.

isActivequeryboolean

Only active (true) or only inactive (false) merchants.

Request example

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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of merchants.

Responses · Field
FieldTypeDescription
itemsarray<PublicMerchantDto>nullable

Items of the requested page.

id
items[].id
string (uuid)

Merchant id.

name
items[].name
stringnullable

Account name.

contactName
items[].contactName
stringnullable

Contact person.

contactPhone
items[].contactPhone
stringnullable

Contact phone.

contactEmail
items[].contactEmail
stringnullable

Contact email.

isActive
items[].isActive
boolean

Whether the merchant can book shipments.

createdAt
items[].createdAt
string (date-time)

Creation time (UTC).

primaryAddress
items[].primaryAddress
PublicMerchantAddressDto

A saved pickup address of a merchant.

id
items[].primaryAddress.id
string (uuid)

Address id.

label
items[].primaryAddress.label
stringnullable

Short label.

contactName
items[].primaryAddress.contactName
stringnullable

Contact person at the address.

contactPhone
items[].primaryAddress.contactPhone
stringnullable

Phone at the address.

country
items[].primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

id
items[].primaryAddress.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].primaryAddress.country.nameAr
stringnullable

Arabic name.

nameEn
items[].primaryAddress.country.nameEn
stringnullable

English name.

city
items[].primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

id
items[].primaryAddress.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].primaryAddress.city.nameAr
stringnullable

Arabic name.

nameEn
items[].primaryAddress.city.nameEn
stringnullable

English name.

district
items[].primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

id
items[].primaryAddress.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].primaryAddress.district.nameAr
stringnullable

Arabic name.

nameEn
items[].primaryAddress.district.nameEn
stringnullable

English name.

addressLine
items[].primaryAddress.addressLine
stringnullable

Street, building and landmark.

shortAddress
items[].primaryAddress.shortAddress
stringnullable

Saudi national short address.

latitude
items[].primaryAddress.latitude
number (double)nullable

Latitude.

longitude
items[].primaryAddress.longitude
number (double)nullable

Longitude.

isPrimary
items[].primaryAddress.isPrimary
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · Example response
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants

#

Create a merchant

API key + secret, or bearer tokenRequired scope: merchants:writeSupports Idempotency-Key

Uses the dashboard's rules: commercial registration number and email are required, the VAT number is required unless notVatRegistered is true, and the primary pickup address is required (country/city/district by names, matched strictly; nothing is created). Data that matches another merchant on the platform is refused with 409 (merchant.email_taken_format, merchant.same_merchant_format) or, when it only looks similar, with 409 merchant.possible_duplicate unless confirmPossibleDuplicate is true. Unlike the dashboard, no merchant login and no email are created. Retries are safe with Idempotency-Key.

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Optional key (up to 128 characters, no spaces; X-Idempotency-Key is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header Idempotent-Replayed: true); the same key with a different body answers 409 idempotency_key_reused. Scoped to your company and credential.

Request body · PublicCreateMerchantRequestapplication/json

The merchant.

FieldTypeDescription
name
required
stringnullable

Account (store) name. Not unique, but a name that matches another merchant on the platform needs confirmPossibleDuplicate. Required, up to 200 characters.

Example: Noor Electronics

contactNamestringnullable

Contact person.

Example: Omar Hassan

contactPhonestringnullable

Contact phone.

Example: 0501234567

contactEmail
required
stringnullable

Contact email. Required; unique across the platform.

Example: orders@noor-electronics.example

commercialRegNo
required
stringnullable

Commercial registration number (or freelance licence number). Required.

Example: 1010123456

taxId
conditional
stringnullable

VAT number. Required unless notVatRegistered is true.

Example: 300123456700003

notVatRegisteredboolean

True when the merchant is not registered for VAT.

Example: false

addressPublicMerchantAddressInput

A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English.

label
address.label
required
stringnullable

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

Example: Main warehouse

contactName
address.contactName
stringnullable

Person to contact at this address (defaults to the merchant name).

Example: Omar Hassan

contactPhone
address.contactPhone
required
stringnullable

Phone at this address. Required.

Example: 0501234567

country
address.country
stringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
address.city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
address.district
required
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
address.addressLine
required
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Warehouse 4

shortAddress
address.shortAddress
conditional
stringnullable

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

Example: RNBA6769

latitude
address.latitude
number (double)nullable

Latitude (optional).

Example: 24.7136

longitude
address.longitude
number (double)nullable

Longitude (optional).

Example: 46.6753

confirmPossibleDuplicateboolean

Confirm that this is a different store even though its registration number, VAT number or name matches another merchant on the platform. Without it such a request is refused with 409 merchant.possible_duplicate.

Example: false

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

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"
  }
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

201The created merchant.

Responses · Field
FieldTypeDescription
idstring (uuid)

Merchant id.

namestringnullable

Account name.

contactNamestringnullable

Contact person.

contactPhonestringnullable

Contact phone.

contactEmailstringnullable

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringnullable

Short label.

contactName
primaryAddress.contactName
stringnullable

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringnullable

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.country.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.country.nameEn
stringnullable

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.city.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.city.nameEn
stringnullable

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.district.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.district.nameEn
stringnullable

English name.

addressLine
primaryAddress.addressLine
stringnullable

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringnullable

Saudi national short address.

latitude
primaryAddress.latitude
number (double)nullable

Latitude.

longitude
primaryAddress.longitude
number (double)nullable

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

201 · Example response
{
  "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
  }
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

409

Conflict

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/merchants/{id}

#

Get a merchant

API key + secret, or bearer tokenRequired scope: merchants:read

Required scope (API key) or equivalent permission (password): merchants:read.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

Request example

GET /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl "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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The merchant with its primary address.

Responses · Field
FieldTypeDescription
idstring (uuid)

Merchant id.

namestringnullable

Account name.

contactNamestringnullable

Contact person.

contactPhonestringnullable

Contact phone.

contactEmailstringnullable

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringnullable

Short label.

contactName
primaryAddress.contactName
stringnullable

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringnullable

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.country.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.country.nameEn
stringnullable

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.city.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.city.nameEn
stringnullable

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.district.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.district.nameEn
stringnullable

English name.

addressLine
primaryAddress.addressLine
stringnullable

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringnullable

Saudi national short address.

latitude
primaryAddress.latitude
number (double)nullable

Latitude.

longitude
primaryAddress.longitude
number (double)nullable

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

200 · Example response
{
  "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
  }
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

PUT

/api/public/v1/merchants/{id}

#

Update a merchant

API key + secret, or bearer tokenRequired scope: merchants:write

Changes the name and contact fields you send; everything else (registration numbers, pricing, banking) is untouched.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

Request body · PublicUpdateMerchantRequestapplication/json

The changes.

FieldTypeDescription
namestringnullable

New account name.

Example: Noor Electronics

contactNamestringnullable

New contact person.

Example: Omar Hassan

contactPhonestringnullable

New contact phone.

Example: 0501234567

contactEmailstringnullable

New contact email.

Example: orders@noor-electronics.example

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

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"
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The updated merchant.

Responses · Field
FieldTypeDescription
idstring (uuid)

Merchant id.

namestringnullable

Account name.

contactNamestringnullable

Contact person.

contactPhonestringnullable

Contact phone.

contactEmailstringnullable

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringnullable

Short label.

contactName
primaryAddress.contactName
stringnullable

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringnullable

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.country.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.country.nameEn
stringnullable

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.city.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.city.nameEn
stringnullable

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

id
primaryAddress.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
primaryAddress.district.nameAr
stringnullable

Arabic name.

nameEn
primaryAddress.district.nameEn
stringnullable

English name.

addressLine
primaryAddress.addressLine
stringnullable

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringnullable

Saudi national short address.

latitude
primaryAddress.latitude
number (double)nullable

Latitude.

longitude
primaryAddress.longitude
number (double)nullable

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

200 · Example response
{
  "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
  }
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/merchants/{id}/addresses

#

List the saved pickup addresses of a merchant

API key + secret, or bearer tokenRequired scope: merchants:read

The primary address first.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

Request example

GET /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses
curl "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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The addresses.

Responses · Field
FieldTypeDescription
idstring (uuid)

Address id.

labelstringnullable

Short label.

contactNamestringnullable

Contact person at the address.

contactPhonestringnullable

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

id
[].country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
[].country.nameAr
stringnullable

Arabic name.

nameEn
[].country.nameEn
stringnullable

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

id
[].city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
[].city.nameAr
stringnullable

Arabic name.

nameEn
[].city.nameEn
stringnullable

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

id
[].district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
[].district.nameAr
stringnullable

Arabic name.

nameEn
[].district.nameEn
stringnullable

English name.

addressLinestringnullable

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimaryboolean

True for the primary address (used by default as the pickup of the merchant's shipments).

200 · Example response
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "country": {},
    "city": {},
    "district": {},
    "isPrimary": false
  }
]
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants/{id}/addresses

#

Add a saved pickup address

API key + secret, or bearer tokenRequired scope: merchants:writeSupports Idempotency-Key

Country, city and district are matched strictly by id, code or name (Arabic or English); nothing is created (geo_* errors with details.field = address). A short address is required for Saudi addresses. The first address of a merchant is always primary.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

Idempotency-Keyheaderstring

Optional key (up to 128 characters, no spaces; X-Idempotency-Key is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header Idempotent-Replayed: true); the same key with a different body answers 409 idempotency_key_reused. Scoped to your company and credential.

Request body · PublicCreateMerchantAddressRequestapplication/json

The address.

FieldTypeDescription
label
required
stringnullable

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

Example: Main warehouse

contactNamestringnullable

Person to contact at this address (defaults to the merchant name).

Example: Omar Hassan

contactPhone
required
stringnullable

Phone at this address. Required.

Example: 0501234567

countrystringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
required
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
required
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Warehouse 4

shortAddress
conditional
stringnullable

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

Example: RNBA6769

latitudenumber (double)nullable

Latitude (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude (optional).

Example: 46.6753

makePrimaryboolean

Make this the primary address (the first address of a merchant is always primary).

Example: false

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

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
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

201The created address.

Responses · Field
FieldTypeDescription
idstring (uuid)

Address id.

labelstringnullable

Short label.

contactNamestringnullable

Contact person at the address.

contactPhonestringnullable

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

id
country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
country.nameAr
stringnullable

Arabic name.

nameEn
country.nameEn
stringnullable

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

id
city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
city.nameAr
stringnullable

Arabic name.

nameEn
city.nameEn
stringnullable

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

id
district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
district.nameAr
stringnullable

Arabic name.

nameEn
district.nameEn
stringnullable

English name.

addressLinestringnullable

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimaryboolean

True for the primary address (used by default as the pickup of the merchant's shipments).

201 · Example response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": false
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

PUT

/api/public/v1/merchants/{id}/addresses/{addressId}

#

Replace a saved pickup address

API key + secret, or bearer tokenRequired scope: merchants:write

The body replaces the whole address (same fields as when adding). The primary flag is unchanged; use the primary route to change it.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

addressId
required
pathstring (uuid)

Address id.

Request body · PublicMerchantAddressInputapplication/json

The address.

FieldTypeDescription
label
required
stringnullable

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

Example: Main warehouse

contactNamestringnullable

Person to contact at this address (defaults to the merchant name).

Example: Omar Hassan

contactPhone
required
stringnullable

Phone at this address. Required.

Example: 0501234567

countrystringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
required
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
required
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Warehouse 4

shortAddress
conditional
stringnullable

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

Example: RNBA6769

latitudenumber (double)nullable

Latitude (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude (optional).

Example: 46.6753

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

PUT /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X PUT "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/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 '{
  "label": "Main warehouse",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "country": "SA",
  "city": "Riyadh",
  "district": "Al Olaya",
  "addressLine": "King Fahd Road, Warehouse 4",
  "shortAddress": "RNBA6769",
  "latitude": 24.7136,
  "longitude": 46.6753
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The updated address.

Responses · Field
FieldTypeDescription
idstring (uuid)

Address id.

labelstringnullable

Short label.

contactNamestringnullable

Contact person at the address.

contactPhonestringnullable

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

id
country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
country.nameAr
stringnullable

Arabic name.

nameEn
country.nameEn
stringnullable

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

id
city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
city.nameAr
stringnullable

Arabic name.

nameEn
city.nameEn
stringnullable

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

id
district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
district.nameAr
stringnullable

Arabic name.

nameEn
district.nameEn
stringnullable

English name.

addressLinestringnullable

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimaryboolean

True for the primary address (used by default as the pickup of the merchant's shipments).

200 · Example response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": false
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or merchant.address_not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

DELETE

/api/public/v1/merchants/{id}/addresses/{addressId}

#

Delete a saved address

API key + secret, or bearer tokenRequired scope: merchants:write

The only address of a merchant cannot be deleted. When the primary one is deleted, the oldest remaining becomes primary.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

addressId
required
pathstring (uuid)

Address id.

Request example

DELETE /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X DELETE "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

204Deleted.

StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or merchant.address_not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants/{id}/addresses/{addressId}/primary

#

Make an address the primary one

API key + secret, or bearer tokenRequired scope: merchants:write

The primary address is the default pickup of the merchant's shipments and the destination of its returns.

Parameters

NameInTypeDescription
id
required
pathstring (uuid)

Merchant id.

addressId
required
pathstring (uuid)

Address id.

Request example

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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The address, now primary.

Responses · Field
FieldTypeDescription
idstring (uuid)

Address id.

labelstringnullable

Short label.

contactNamestringnullable

Contact person at the address.

contactPhonestringnullable

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

id
country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
country.nameAr
stringnullable

Arabic name.

nameEn
country.nameEn
stringnullable

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

id
city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
city.nameAr
stringnullable

Arabic name.

nameEn
city.nameEn
stringnullable

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

id
district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
district.nameAr
stringnullable

Arabic name.

nameEn
district.nameEn
stringnullable

English name.

addressLinestringnullable

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimaryboolean

True for the primary address (used by default as the pickup of the merchant's shipments).

200 · Example response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": false
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or merchant.address_not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference