1. Parcels
  2. Create & Update Parcel

Parcels

Create & Update Parcel

Create Parcel

POST
`/v1/parcels`

Create a standalone parcel. Requires the parcels:write scope. Parcels can also be created through fulfillments, manifests or shipments.

Required Parameters

location_id string
The ID of the location to associate the parcel with.

name string
The name of the parcel. Maximum 128 characters.

Optional Parameters

type string
Type of the parcel.

status string
Status of the parcel.

length number
Length of the parcel.

width number
Width of the parcel.

height number
Height of the parcel.

weight number
Weight of the parcel.

max_weight_domestic number
Maximum domestic weight for the parcel.

max_weight_international number
Maximum international weight for the parcel.

special_handling_tags string[]
Array of special handling tags.

external_container_id string
External container identifier.

container_number string
Container number.

tracking_number string
Tracking number for the parcel.

label_url string
URL to the parcel label.

layout_id string
The ID of the layout to associate with the parcel.

unpacked boolean
Whether the parcel has been unpacked. Default: false.

received boolean
Whether the parcel has been received. Default: false.

defective boolean
Whether the parcel is defective.

missing boolean
Whether the parcel is missing.

contents array
Array of parcel content objects.

metadata object
Custom metadata key-value pairs.

Example Request

js 
        const response = await fetch("https://api.packagex.io/v1/parcels", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    location_id: "loc_abc123xyz",
    name: "Parcel A",
    length: 10,
    width: 10,
    height: 10,
    weight: 5,
  }),
}).then((res) => res.json());

const parcel = response.data;

Update Parcel

POST
`/v1/parcels/:parcel`

Updates an existing parcel and its contents using the id of the parcel.

Request Body

The request body accepts properties for both the parcel and its contents. All fields are optional and only provided fields will be updated.

Parcel Properties

js 
        {
  // Core Properties
  type: string,                    // Type of the parcel
  status: string,
  special_handling_tags: string[],

  // Dimensions and Weight
  length: number,
  width: number,
  height: number,
  weight: number,

  // Identifiers and References
  external_container_id: string,
  container_number: string,
  tracking_number: string,
  label_url: string,
  layout_id: string,

  // Status Flags
  defective: boolean,
  missing: boolean,
  received: boolean,
  unpacked: boolean,

  contents: [
    {
      id: string,
      special_handling_tags: string[],
      item_id: string,
      sku: string,
      gtin: string
      packed_qty: number,
      is_asset: boolean,
      comment: string,
      verified_qty: number,
      requested_qty: number,
      defective_qty: number,
      value_added_services: string[]
    }
  ]
}

Example Request

The parcel and its contents can be updated as follows

js 
        {
  "status": "inbound_transit",
  "layout_id": "lay_XkTCC8FvgM65akxw",
  "special_handling_tags": ["fragile", "dry_cleaning"],
  "length": 20,
  "width": 20,
  "height": 20,
  "weight": 70,
  "contents": [
    {
      "id": "cont_abc1231xyz",
      "special_handling_tags": ["fragile"],
      "item_id": "item_czhgjrk5JaVvyATPDbyURp",
      "verified_qty": 2,
      "requested_qty": 3,
      "defective_qty": 5
    }
  ]
}

const res = await fetch(`https://api.packagex.io/v1/parcels/${parcel_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());
Previous <- Statuses and Events
Next Retrieve Parcel ->