Update Shipment

Updates an existing shipment with new information or metadata. Only certain fields can be updated after creation.

Endpoint

PUT /v1/shipments/{id}
PATCH /v1/shipments/{id}

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Description
id	string	The ID of the shipment to update.

Request Body

Parameter	Type	Required	Description
reference_number	string	No	Your internal reference number for this shipment.
metadata	object	No	Arbitrary metadata for the shipment.
enable_tracking	boolean	No	Whether to enable tracking for the shipment.

Example Request Body

{
  "reference_number": "UPDATED-ORD-2025-001",
  "metadata": {
    "customer_notes": "Fragile items, handle with care."
  }
}

Response

200 OK

{
  "data": {
    "id": "sh_123456",
    "reference_number": "UPDATED-ORD-2025-001",
    "shipping_channel_id": "ch_123456",
    "provider_shipment_id": "DHL-ABC-123",
    "status": "created",
    "total_price": 15.50,
    "currency": "USD",
    "created_at": "2025-08-10T10:00:00Z",
    "updated_at": "2025-08-10T10:05:00Z"
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - You don't have permission to update this shipment
404	Not Found - The specified shipment could not be found
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Example Request

cURL

curl -X PUT \
  https://api.shipping-channels.com/v1/shipments/sh_123456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_number": "UPDATED-ORD-2025-001",
    "metadata": {
      "customer_notes": "Fragile items, handle with care."
    }
  }'

PHP

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.shipping-channels.com/v1/shipments/sh_123456', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        "reference_number" => "UPDATED-ORD-2025-001",
        "metadata" => [
            "customer_notes" => "Fragile items, handle with care."
        ]
    ],
]);

$data = json_decode($response->getBody(), true);

JavaScript

fetch('https://api.shipping-channels.com/v1/shipments/sh_123456', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    reference_number: "UPDATED-ORD-2025-001",
    metadata: {
      customer_notes: "Fragile items, handle with care."
    }
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));