Create Shipment

Registers shipment details before booking with a carrier option.

Body parameters

Name	Type	Required	Description
merchant_id	string	Yes	Merchant UUID that owns the shipment.
merchant_order_ref	string	Yes	External merchant order reference.
collection_date	string	No	Collection datetime in ISO-8601 format.
pickup_address	object	Yes	Collection address object.
dropoff_address	object	Yes	Delivery address object.
parcels	array	Yes	List of parcel objects.
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' => [
    'shipment_id' => 'shp_101',
    'merchant_id' => 'mrc_001',
    'environment_id' => 'env_live_001',
    'merchant_order_ref' => 'ORD-8842',
    'collection_date' => '2026-02-18',
    'status' => 'ready',
    'pickup_address' => [
      'location_id' => 'loc_001',
      'name' => 'Warehouse A',
      'address_line_1' => '12 Jet Park Rd',
      'city' => 'Johannesburg',
      'country' => 'ZA',
      'post_code' => '1459',
      'latitude' => -26.1367,
      'longitude' => 28.2225
    ],
    'dropoff_address' => [
      'location_id' => 'loc_002',
      'name' => 'Customer Address',
      'address_line_1' => '90 Bree St',
      'city' => 'Cape Town',
      'country' => 'ZA',
      'post_code' => '8001',
      'latitude' => -26.1367,
      'longitude' => 28.2225
    ],
    'pickup_instructions' => 'Collect from loading bay 2',
    'dropoff_instructions' => 'Call on arrival',
    'ready_at' => '2026-02-18T07:30:00Z',
    'metadata' => [
      'source' => 'shopify'
    ],
    'parcels' => [
      [
        'parcel_id' => 'prc_001',
        'weight_kg' => '3.50',
        'length_cm' => '35',
        'width_cm' => '22',
        'height_cm' => '18',
        'declared_value' => '899.00',
        'contents_description' => 'Electronics accessories'
      ]
    ],
    'created_at' => '2026-02-17T10:22:00Z'
  ]
];

Request examples

curl -X POST \
  "https://api.spaces.za.com/api/v1/shipments" \
  -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": "6 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
    }
  ]
}'