GROperator

Pricing

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

POST

/api/public/v1/pricing/quote

#

Quote a shipment price

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

Prices exactly like shipment creation (rate card of the merchant, zone of the destination, handling surcharges, COD fee) and applies the company's coverage, but creates nothing: no shipment, no tracking number, no quota is used. total equals the shipping fee the created shipment will carry. Without merchant the company's default pricing applies.

A destination (or pickup) outside the company's coverage is not an error: the answer is 200 with deliverable: false and reason set to destination_not_covered, pickup_not_covered or rate_card_not_found. Locations that do not exist answer 422 with the geo_* codes and details.field = pickup or recipient.

Request body · PublicQuoteRequestapplication/json

The shipment to price.

FieldTypeDescription
merchant
conditional
stringnullable

Merchant id or exact account name; the merchant's own rate card applies. Optional: without it the company's default pricing is used. A merchant login always quotes for itself. Required for return quotes.

Example: Noor Electronics

pickupPublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

country
pickup.country
stringnullable

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

Example: SA

city
pickup.city
required
stringnullable

City id, code or name. Required.

Example: Jeddah

district
pickup.district
stringnullable

District id, code or name. Optional for a quote; when sent it must exist.

Example: Al Rawdah

recipientPublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

country
recipient.country
stringnullable

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

Example: SA

city
recipient.city
required
stringnullable

City id, code or name. Required.

Example: Jeddah

district
recipient.district
stringnullable

District id, code or name. Optional for a quote; when sent it must exist.

Example: Al Rawdah

parcelPublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

weightKg
parcel.weightKg
required
number (double)

Actual weight in kilograms, greater than 0.

Example: 1.5

lengthCm
parcel.lengthCm
required
number (double)

Length in centimetres, greater than 0.

Example: 20

widthCm
parcel.widthCm
required
number (double)

Width in centimetres, greater than 0.

Example: 15

heightCm
parcel.heightCm
required
number (double)

Height in centimetres, greater than 0.

Example: 10

pieces
parcel.pieces
integer (int32)nullable

Number of pieces (default 1).

Example: 1

description
parcel.description
stringnullable

What is inside (optional, shown on the label).

Example: Mobile phone case

declaredValue
parcel.declaredValue
number (double)nullable

Declared value of the goods (default 0).

Example: 250

fragile
parcel.fragile
boolean

Fragile goods.

Example: false

requiresColdChain
parcel.requiresColdChain
conditional
boolean

Needs cold chain; then coldChainRange is required.

Example: false

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable goods.

Example: false

hazardous
parcel.hazardous
boolean

Hazardous goods.

Example: false

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

Example: false

liquid
parcel.liquid
boolean

Liquid goods.

Example: false

highValue
parcel.highValue
boolean

High-value goods.

Example: false

paymentPublicPaymentInput

Cash on delivery and freight payment.

codAmount
payment.codAmount
number (double)nullable

Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for return.

Example: 199.5

freightOnDelivery
payment.freightOnDelivery
booleannullable

True when the recipient pays the shipping fee on delivery.

Example: false

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

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 /pricing/quote
curl -X POST "https://api.goldrock.live/api/public/v1/pricing/quote" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant": "Noor Electronics",
  "pickup": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya"
  },
  "recipient": {
    "country": "SA",
    "city": "Jeddah",
    "district": "Al Rawdah"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10
  },
  "payment": {
    "codAmount": 199.5
  },
  "serviceType": "delivery",
  "serviceTier": "standard"
}'

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

Responses

200The quote.

Responses · Field
FieldTypeDescription
deliverableboolean

False when the company does not cover the pickup or the destination (see reason).

reasonstringnullable

destination_not_covered, pickup_not_covered or rate_card_not_found when not deliverable.

shippingFeenumber (double)nullable

Shipping fee without the COD fee (weight price plus handling surcharges).

codFeenumber (double)nullable

Fee charged for collecting cash on delivery.

totalnumber (double)nullable

What the shipment will be charged: shippingFee + codFee. Equals payment.shippingFee of the created shipment.

chargeableWeightKgnumber (double)nullable

The larger of actual and volumetric weight.

zonePublicZoneRef

A pricing zone.

id
zone.id
string (uuid)

Zone id.

name
zone.name
stringnullable

Zone name.

breakdownarray<PublicQuoteLineDto>nullable

Price lines; they add up to total.

code
breakdown[].code
stringnullable

baseShipping, handling, codFee or reverseAdjustment.

label
breakdown[].label
stringnullable

Readable label (the handling flag name for handling lines).

amount
breakdown[].amount
number (double)

Amount of the line.

200 · Example response
{
  "deliverable": true,
  "reason": null,
  "shippingFee": 25,
  "codFee": 5,
  "total": 30,
  "chargeableWeightKg": 1.5,
  "zone": {
    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",
    "name": "Zone 2"
  },
  "breakdown": [
    {
      "code": "baseShipping",
      "label": "Base shipping",
      "amount": 25
    },
    {
      "code": "codFee",
      "label": "Cash on delivery fee",
      "amount": 5
    }
  ]
}
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

The merchant was not found (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