GROperator

Pricing quotes

POST /pricing/quote tells you what a shipment would cost and whether you can deliver it, without creating anything: no shipment, no tracking number and no quota used. It prices exactly like shipment creation: the merchant's rate card, the zone of the destination, handling surcharges and the cash-on-delivery fee. Scope: pricing:read.

The body mirrors a shipment, with less detail: places, parcel, payment, service type and tier.

Field Details
merchant Merchant id or exact account name; that merchant's rate card applies. Optional: without it the company's default pricing is used. Required for return quotes. A merchant login always quotes for itself
pickup city is required; country is optional; district is optional (when you send it, it must exist)
recipient The same three fields
parcel weightKg, lengthCm, widthCm, heightCm are required. The handling flags (fragile, liquid, ...) can add surcharges
payment.codAmount Adds the cash-on-delivery fee
serviceType delivery (default), exchange or return
serviceTier standard (default), express or sameDay
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"
}'
JSON
{
  "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
    }
  ]
}
Field Meaning
deliverable false when your company does not cover the pickup or the destination, or has no rate card
reason Why it is not deliverable: destination_not_covered, pickup_not_covered or rate_card_not_found
shippingFee The fee without the COD fee: weight price plus handling surcharges
codFee The fee for collecting cash on delivery
total shippingFee + codFee. This equals the payment.shippingFee of the shipment you then create
chargeableWeightKg The larger of the actual and the volumetric weight
zone The pricing zone that applied
breakdown The price lines (baseShipping, handling, codFee, reverseAdjustment); they add up to total

A destination or pickup outside your coverage is not an error. The answer is 200 with deliverable: false and no prices, so you can show "we do not deliver there yet" instead of a failure:

JSON
{
  "deliverable": false,
  "reason": "destination_not_covered",
  "shippingFee": null,
  "codFee": null,
  "total": null,
  "chargeableWeightKg": null,
  "zone": null,
  "breakdown": []
}

A place that does not exist at all is an error: 422 with the geo_* codes and details.field set to pickup or recipient, see Places by name.

For a public price calculator, leave merchant out and the company's default pricing applies:

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 '{
  "pickup": {
    "country": "SA",
    "city": "Riyadh"
  },
  "recipient": {
    "country": "SA",
    "city": "Dammam"
  },
  "parcel": {
    "weightKg": 2,
    "lengthCm": 30,
    "widthCm": 20,
    "heightCm": 15
  },
  "serviceTier": "express"
}'

Call the quote from your server and return only what the page needs. Quote again when the visitor changes the route, weight, service tier or COD amount, and quote one more time just before creating the shipment, because the shipment is priced with the rate card at creation time.