Request Quote

Submit shipment dimensions and route details to receive one or more carrier quote options.

Body parameters

Name	Type	Required	Description
merchant_id	string	Yes	Merchant UUID requesting the quote.
merchant_order_ref	string	No	Optional merchant order reference.
collection_date	string	No	Requested collection datetime in ISO-8601 format.
pickup_address	object	Yes	Origin address object.
pickup_address.name	string	No	Pickup location name.
pickup_address.code	string	No	Pickup address code.
pickup_address.company	string	No	Pickup company name.
pickup_address.address_line_1	string	Yes	Primary pickup street line.
pickup_address.address_line_2	string	No	Secondary pickup street line.
pickup_address.town	string	No	Pickup town/suburb.
pickup_address.city	string	Yes	Pickup city.
pickup_address.province	string	No	Pickup province/state.
pickup_address.post_code	string	No	Pickup postal code.
pickup_address.country	string	Yes	Two-letter country code.
pickup_address.first_name	string	No	Pickup contact first name.
pickup_address.last_name	string	No	Pickup contact last name.
pickup_address.phone	string	No	Pickup contact phone number.
pickup_address.latitude	number	No	Pickup latitude.
pickup_address.longitude	number	No	Pickup longitude.
pickup_address.google_place_id	string	No	Google place identifier.
dropoff_address	object	Yes	Destination address object.
dropoff_address.name	string	No	Dropoff location name.
dropoff_address.code	string	No	Dropoff address code.
dropoff_address.company	string	No	Dropoff company name.
dropoff_address.address_line_1	string	Yes	Primary dropoff street line.
dropoff_address.address_line_2	string	No	Secondary dropoff street line.
dropoff_address.town	string	No	Dropoff town/suburb.
dropoff_address.city	string	Yes	Dropoff city.
dropoff_address.province	string	No	Dropoff province/state.
dropoff_address.post_code	string	No	Dropoff postal code.
dropoff_address.country	string	Yes	Two-letter country code.
dropoff_address.first_name	string	No	Dropoff contact first name.
dropoff_address.last_name	string	No	Dropoff contact last name.
dropoff_address.phone	string	No	Dropoff contact phone number.
dropoff_address.latitude	number	No	Dropoff latitude.
dropoff_address.longitude	number	No	Dropoff longitude.
dropoff_address.google_place_id	string	No	Google place identifier.
parcels	array	Yes	Parcel items in this quote request.
parcels[].title	string	No	Parcel label/title.
parcels[].weight_kg	number	Yes	Parcel weight in kilograms.
parcels[].length_cm	number	Yes	Parcel length in centimeters.
parcels[].width_cm	number	Yes	Parcel width in centimeters.
parcels[].height_cm	number	Yes	Parcel height in centimeters.

Example response

<?php

return [
  'success' => true,
  'data' => [
    'quote_id' => 'quote_123',
    'merchant_order_ref' => 'ORD-8842',
    'merchant_id' => 'mrc_001',
    'environment_id' => 'env_live_001',
    'shipment_id' => 'shp_101',
    'status' => 'pending',
    'requested_at' => '2026-02-17T10:22:00Z',
    'expires_at' => '2026-02-17T11:22:00Z',
    'options' => [
      [
        'quote_option_id' => 'qopt_001',
        'carrier_code' => 'fastship',
        'service_code' => 'next_day',
        'currency' => 'ZAR',
        'amount' => '225.00',
        'tax_amount' => '33.75',
        'total_amount' => '258.75',
        'eta_from' => '2026-02-18T08:00:00Z',
        'eta_to' => '2026-02-18T17:00:00Z',
        'rules' => [
          'max_weight_kg' => 25
        ]
      ]
    ],
    'selected_option' => null
  ]
];

Request examples

curl -X POST \
  "https://api.spaces.za.com/api/v1/quotes" \
  -H "Authorization: Bearer <token>" \\
  -H "Content-Type: application/json" \\
  --data '{
  "merchant_id": "mrc_001",
  "merchant_order_ref": "ORD-8842",
  "collection_date": "2026-02-18T09:00:00Z",
  "pickup_address": {
    "name": "Warehouse A",
    "code": "WH-A",
    "company": "PicknDrop",
    "address_line_1": "60 Newline Road",
    "address_line_2": "Sunningdale",
    "town": "Sunningdale",
    "city": "Cape Town",
    "province": "Western Cape",
    "post_code": "7441",
    "country": "ZA",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+27-21-555-1234",
    "latitude": -33.7801,
    "longitude": 18.4567,
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4"
  },
  "dropoff_address": {
    "name": "Customer",
    "code": "CUST-1001",
    "company": "Customer Co",
    "address_line_1": "10 Newline Road",
    "address_line_2": "Sunningdale",
    "town": "Sunningdale",
    "city": "Cape Town",
    "province": "Western Cape",
    "post_code": "7441",
    "country": "ZA",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+27-21-555-5678",
    "latitude": -33.7812,
    "longitude": 18.4588,
    "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
  },
  "parcels": [
    {
      "title": "ABC",
      "weight_kg": 1,
      "length_cm": 10,
      "width_cm": 10,
      "height_cm": 10
    }
  ]
}'