1. Shipments
  2. Update Shipments

Shipments

Update Shipments

This endpoint enables you to update various aspects of an existing shipment, including tracking information, status updates, and associated metadata.

POST
`/v1/shipments/:shipment`

Request Parameters

Path Parameters

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

Request Body

The request body can include any combination of the following fields:

js
        {
  // Basic Information
  type: "outbound" | "inbound",
  coordinates: [number, number],
  estimated_delivery_at: string | number | Date,
  pickup_at: string | number | Date,

  // Reference Numbers
  rma_number: string,
  invoice_number: string,
  order_number: string,
  purchase_order: string,
  reference_number: string,
  account_id: string,

  // Tracking Information
  tracking_number: string,
  provider_id: string,
  service_level_id: string,

  weight: number,

  // Additional Information
  notes: string,
  tags: string[],
  metadata: object,

  // Tracking Updates
  tracking_update: {
    container_id: string,
    status: string,
    layout_id: string,
    location_id: string,
    contact_id: string,
    user_id: string,
    comment: string,
    address: string | object
    images: string[]
  }
}

      

Request Examples

Basic Information Update

js
        const body = {
  tracking_number: "1Z999999999999999",
  provider_id: "ups",
  estimated_delivery_at: "2025-02-22T15:00:00Z",
  pickup_at: "2025-02-22T15:00:00Z",
};

const response = await fetch(`https://api.packagex.io/v1/shipments/${shipment_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
}).then((res) => res.json());

const shipment = response.data;

      

Status Update Example

js
        const body = {
  tracking_update: {
    status: "in_transit",
    location_id: "loc_abc123",
    comment: "Package picked up from sender",
    images: ["https://example.com/image1.jpg"],
  },
};

const response = await fetch(`https://api.packagex.io/v1/shipments/${shipment_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
}).then((res) => res.json());

const shipment = response.data;

      

Additional Information Update Example

js
        const body = {
  rma_number: "9999",
  invoice_number: "443322",
  order_number: "1212",
  purchase_order: "77777",
  reference_number: "8888",
  account_id: "874690",
  notes: "This is a test shipment",
  tags: ["express_priority", "confidential"],
  metadata: {
    department: "Sales",
    priority: "High",
  }
};

const response = await fetch(`https://api.packagex.io/v1/shipments/${shipment_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
}).then((res) => res.json());

const shipment = response.data;

      

Update Restrictions

  1. Container-Related Restrictions

    • Cannot update status or location for shipments in containers. Either unlink the shipment or update the container directly.
  2. Purchased Shipment Restrictions

    • Cannot modify provider_id
    • Cannot update tracking_number
    • Cannot change service_level_id
    • Cannot modify dimensions or weight
  3. Status Update Restrictions

    • Must provide valid status transitions
    • Location and layout must be compatible

Error Handling

Common error scenarios include:

  1. Invalid Updates
js
        {
  "error": {
    "code": "update.disabled",
    "errors": ["container_id"],
    "message": "Cannot update the status or location on a shipment in a container. Either unlink the shipment from the container or update the container directly.",
    "status": 400
  }
}

      
  1. Validation Errors
js
        {
  "error": {
    "code": "small_tracking_number",
    "errors": ["tracking_number"],
    "message": "Invalid tracking number: The tracking number must be at least 10 characters long. Please provide a complete and valid tracking number.",
    "status": 400
  }
}

      
  1. Permission Errors
js
        {
  "error": {
    "code": "invalid:contact",
    "errors": ["contact_id"],
    "message": "Contact does not belong to the organization",
    "status": 400
  }
}