Create Tracking Parcel

Creates a new tracking parcel for monitoring through the Shipping Channels platform.

Endpoint

POST /v1/tracking-parcels

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

Parameter	Type	Required	Description
tracking_number	string	Yes	The carrier's tracking number
shipping_channel_id	string	Yes	ID of an active shipping channel
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
check_delay_hours	integer	No	Number of hours to wait before checking for status updates. Default is 6.
max_checks	integer	No	Maximum number of checks to perform. Default is 20.
external_data	object	No	Arbitrary external data to associate with the parcel.

Example Request Body

{
  "tracking_number": "1234567890",
  "shipping_channel_id": "ch_123456",
  "recipient_name": "John Doe",
  "recipient_email": "john@example.com",
  "recipient_phone": "+1234567890",
  "check_delay_hours": 12,
  "max_checks": 30,
  "external_data": {
    "order_id": "ORD-789",
    "customer_id": "CUST-456"
  }
}

Response

201 Created

{
  "data": {
    "id": "tp_123456",
    "tracking_number": "1234567890",
    "shipping_channel_id": "ch_123456",
    "status": "created",
    "recipient_name": "John Doe",
    "recipient_email": "john@example.com",
    "recipient_phone": "+1234567890",
    "check_delay_hours": 12,
    "max_checks": 30,
    "external_data": {
      "order_id": "ORD-789",
      "customer_id": "CUST-456"
    },
    "created_at": "2025-04-07T12:00:00Z",
    "updated_at": "2025-04-07T12:00:00Z"
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - The specified shipping channel 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": {
      "tracking_number": [
        "The tracking number is required."
      ],
      "shipping_channel_id": [
        "The selected shipping channel is invalid."
      ]
    }
  }
}

Example Request

cURL

curl -X POST \
  https://api.shipping-channels.com/v1/tracking-parcels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1234567890",
    "shipping_channel_id": "ch_123456",
    "recipient_name": "John Doe",
    "recipient_email": "john@example.com",
    "recipient_phone": "+1234567890",
    "check_delay_hours": 12,
    "max_checks": 30,
    "external_data": {
      "order_id": "ORD-789",
      "customer_id": "CUST-456"
    }
  }'

PHP

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

$response = $client->request('POST', 'https://api.shipping-channels.com/v1/tracking-parcels', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'tracking_number' => '1234567890',
        'shipping_channel_id' => 'ch_123456',
        'recipient_name' => 'John Doe',
        'recipient_email' => 'john@example.com',
        'recipient_phone' => '+1234567890',
        'check_delay_hours' => 12,
        'max_checks' => 30,
        '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', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    tracking_number: '1234567890',
    shipping_channel_id: 'ch_123456',
    recipient_name: 'John Doe',
    recipient_email: 'john@example.com',
    recipient_phone: '+1234567890',
    check_delay_hours: 12,
    max_checks: 30,
    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));

Tracking Status

Upon creation, the tracking parcel status will be set to created. The system will automatically begin tracking the parcel and updating its status based on information from the shipping provider.