Containers

Update Containers

When updating a container, you can update the tracking status which will be appended to the history of the container and can trigger notifications if those are set up. You can also send the location coordinates as often as you would like, though we recommend limiting this to a maximum of once every 30 seconds.

Update Container

POST

`/v1/containers/:container`

Request Body Example

        const data = {
  add: ["ship_82A6o62SfaFeLRctFCMBrt"],
  remove: ["ship_93B7p73TgbGfMSdtGDNCsu"],
  tracking_update: {
    status: "out_for_delivery",
    comment: "Vehicle departed from distribution center",
    address: {
      line1: "123 Delivery St",
      city: "San Diego",
      state: "California",
      postal_code: "92101",
      country: "US"
    },
    images: ["data:image/jpeg;base64,/9j/4AAQSkZJRg..."]
  },
  location_id: "loc_warehouse_main",
  layout_id: "lay_zone_a_shelf_1",
  coordinates: [40.7531386, -73.9894616],
  user_id: "user_45D8r84UhcHfNTeuHEODpv",
  metadata: {
    route_number: "RT-123",
    priority_level: "high"
  }
};

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

const container = res.data;

Validations

Shipment Ownership:
- All shipments must belong to the same organization as the API key.
- Shipments cannot be already assigned to another container.
Layout Assignment:
- A layout_id cannot be assigned without a valid location_id.
- The layout must belong to the specified location.

Comment Parameter

The comment parameter is an optional object that lets you attach specific comments to tracking updates for different shipment groups within the same request. This is useful when a single update adds some shipments, removes others, and also propagates a status to shipments already in the container — each group can carry its own message.

Key	Applies to
`comment.add`	Shipments being added — comment appears on their `added_to_container` tracking update
`comment.remove`	Shipments being removed — comment appears on their `removed_from_container` tracking update
`comment.existing`	Shipments already in the container that are not being added or removed

When comment is omitted, the tracking_update.comment field is used as before and behaviour is unchanged.

Add comment

        const data = {
  add: ["ship_newA1B2C3"],
  comment: {
    add: "New package loaded at hub"
  }
};

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

Remove comment

        const data = {
  remove: ["ship_oldX9Y8Z7"],
  comment: {
    remove: "Package returned to sender"
  }
};

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

All three comment keys together

        const data = {
  add: ["ship_newA1B2C3"],
  remove: ["ship_oldX9Y8Z7"],
  comment: {
    add: "New package loaded at hub",
    remove: "Package returned to sender",
    existing: "Continuing delivery route"
  }
};

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

Update Containers