Update Tracking Parcel

Updates an existing tracking parcel with new information or metadata.

Endpoint

PUT /v1/tracking-parcels/{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 tracking parcel to update.

Request Body

Parameter	Type	Required	Description
recipient_name	string	No	Name of the recipient
recipient_email	string	No	Email of the recipient
recipient_phone	string	No	Phone number of the recipient
external_data	object	No	Arbitrary external data to associate with the parcel.

Note: You cannot update the tracking_number or shipping_channel_id of an existing tracking parcel. If you need to change these, you should create a new tracking parcel.

Example Request Body

{
  "recipient_name": "John Smith",
  "recipient_email": "john.smith@example.com",
  "recipient_phone": "+1987654321",
  "external_data": {
    "order_id": "ORD-789",
    "customer_id": "CUST-456"
  }
}

Response

200 OK

{
  "data": {
    "id": "tp_123456",
    "tracking_number": "1234567890",
    "shipping_channel_id": "ch_123456",
    "status": "in_transit",
    "recipient_name": "John Smith",
    "recipient_email": "john.smith@example.com",
    "recipient_phone": "+1987654321",
    "external_data": {
      "order_id": "ORD-789",
      "customer_id": "CUST-456"
    },
    "created_at": "2025-04-06T10:00:00Z",
    "updated_at": "2025-04-07T15:30: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 tracking parcel
404	Not Found - The specified tracking parcel 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

Validation Errors

If there are validation errors, the response will include details:

{
  "error": {
    "message": "The given data was invalid.",
    "errors": {
      "recipient.email": [
        "The email must be a valid email address."
      ]
    }
  }
}

Example Request

cURL

curl -X PUT \
  https://api.shipping-channels.com/v1/tracking-parcels/tp_123456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "John Smith",
    "recipient_email": "john.smith@example.com",
    "recipient_phone": "+1987654321",
    "external_data": {
      "order_id": "ORD-789",
      "customer_id": "CUST-456"
    }
  }'

PHP

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

$response = $client->request('PUT', 'https://api.shipping-channels.com/v1/tracking-parcels/tp_123456', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'recipient_name' => 'John Smith',
        'recipient_email' => 'john.smith@example.com',
        'recipient_phone' => '+1987654321',
        'external_data' => [
            'order_id' => 'ORD-789',
            'customer_id' => 'CUST-456',
        ],
    ],
]);

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

JavaScript

fetch('https://api.shipping-channels.com/v1/tracking-parcels/tp_123456', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    recipient_name: 'John Smith',
    recipient_email: 'john.smith@example.com',
    recipient_phone: '+1987654321',
    external_data: {
      order_id: 'ORD-789',
      customer_id: 'CUST-456'
    }
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Note

You can only update external tracking parcels. Internal tracking parcels cannot be updated via this endpoint.

Updates to tracking parcels only affect the metadata associated with the tracking parcel (recipient information, external data). The tracking process and status updates are handled automatically by the system and cannot be manually modified.