Update Shipment

Updates shipment details before delivery completion.

Path parameters

Name	Type	Required	Description
shipment_id	string	Yes	Shipment identifier.

Body parameters

Name	Type	Required	Description
merchant_order_ref	string	No	Updated merchant order reference.
collection_date	string	No	Updated collection datetime in ISO-8601 format.
pickup_address	object	No	Updated pickup address object.
dropoff_address	object	No	Updated dropoff address object.
pickup_instructions	string	No	Updated pickup instructions.
dropoff_instructions	string	No	Updated dropoff instructions.
ready_at	string	No	Updated ready datetime in ISO-8601 format.
metadata	object	No	Arbitrary metadata object.
parcels	array	No	Updated parcel list.
parcels[].weight_kg	number	No	Parcel weight in kilograms.
parcels[].length_cm	number	No	Parcel length in centimeters.
parcels[].width_cm	number	No	Parcel width in centimeters.
parcels[].height_cm	number	No	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' => 'Warehouse A',
      'address_line_1' => '95 Bree St',
      'city' => 'Cape Town',
      'country' => 'ZA',
      'post_code' => '1459',
      '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 PATCH \
  "https://api.spaces.za.com/api/v1/shipments/shp_101" \
  -H "Authorization: Bearer <token>" \\
  -H "Content-Type: application/json" \\
  --data '{
  "dropoff_address": {
    "address_line_1": "95 Bree St",
    "city": "Cape Town",
    "country": "ZA"
  },
  "dropoff_instructions": "Call 5 minutes before arrival",
  "metadata": {
    "priority": "high"
  }
}'