Deliveries

Create and Update Deliveries

A delivery represents one or more parcels being transported to a recipient. Deliveries are typically generated automatically when senders create shipments in the system. However, as a shipping provider, you can also create deliveries manually, which will automatically generate corresponding shipment records for senders.

As a shipping provider, you are able to update the status and location properties of the delivery, which will update the sender and recipient via webhooks and notifications.

Create Delivery

Creating a delivery is pretty straight forward. Like for a shipment, you'll provide information about the sender, recipient, parcels, and the location_id that will initially be assigned the shipment.

POST

`/v1/deliveries`

Required Fields

location_id: The initial location identifier for the delivery
rate_id: Rate identifier for the delivery (can be set through organization defaults)
Either sender or recipient must include at least one of: address, contact_id, or email

Request Body Structure

Sender and Recipient Information

Both sender and recipient information can be specified in multiple ways:
- Using an existing contact ID
- Using an email address to reference an existing contact
- Providing complete contact details including:
  - name: Full name
  - email: Valid email address
  - phone: Contact phone number (optional)
  - business: Business name (optional)
  - address: Address information
Address Handling

Addresses information an be specified in three different formats:
- Single String Format (with optional second line):
js
```
        {
  address: "500 7th ave, New York, NY, 10018",
  address_line2: "Floor 10" // Optional
}

      
```
- Structured Object Format:
js
```
        {
  address: {
    line1: "500 7th ave",
    line2: "Floor 10",
    city: "New York",
    state: "NY",
    postal_code: "10018",
    country_code: "US"        // Country name, defaults to US
  }
}

      
```
- Address ID Reference:
js
```
        {
  address: "addr_11fkZ8wQzscUj9SZaX1By1";
}

      
```
- Location ID Reference:
js
```
        {
  address: "loc_11fkZ8wQzscUj9SZaX1By1";
}

      
```

Parcel Information

Parcels can be specified using custom dimensions.

        {
  parcels: [
    {
      length: number, // inches
      width: number, // inches
      height: number, // inches
      weight: number, // lbs
    },
  ];
}

Additional Request Body

type string
Type of delivery. Will always be inbound
manifest_id string
The ID of the manifest associated with this delivery.
template_id string
Custom template for shipping labels.
fulfillment_id | fulfillment string
The ID of the fulfillment associated with this delivery.
scan_id | scan string
The ID of the scan associated with this delivery.
tracking_number string
Custom tracking number (minimum 10 characters).

options object
The delivery creation supports numerous configuration options.

Show Details

Property	Type	Description
options.checkout_total	number	Order total amount.
options.lead_time_mins	number	Processing time before pickup.
options.max_delivery_days	number	Maximum delivery duration.
options.provider_instructions	string	Instructions for delivery provider.
options.provider_timeout	number	Provider response timeout.
options.providers	string[]	Array of allowed provider IDs. See *Providers*
options.rate_types	string[]	Supported rate types. Can either be `delivery`, `pickup` or `received`
options.service_levels	string[]	Allowed service levels. See *Service Levels*
options.request_provider_pickup	boolean	Enable provider pickup.
options.same_day_tip_amount	number	Tip amount for same-day delivery.
options.verify_addresses	boolean	Enable address verification.
options.return_other_rates	boolean	Include alternative rate options.
options.tracker_chained_status	*TrackingStatusOutstanding*	Configure status chain behavior.
options.tracker_auto_close_shipments_option	*TrackerCloseShipmentsOption*	Auto-close configuration.
options.tracker_auto_close_shipments_status	*TrackerCloseShipmentsStatus*	Status for auto-closing.

        const delivery = {
  sender: {
    name: "Jamie Jones",
    email: "jamie@example.com",
    phone: "4844836699",
    address: {
      line1: "500 7th Ave",
      line2: "Floor 10",
      city: "New York",
      state: "NY",
      postal_code: "10018",
    },
  },
  recipient: {
    name: "Ashley Young",
    email: "ashley@example.com",
    phone: "4844836699",
    address: "3 Brewster Rd, Newark, NJ, 07114",
  },
  parcels: [
    {
      length: 5,
      width: 5,
      height: 5,
      weight: 2,
    },
  ],
  location_id: "loc_czhgjrk5JaVvyATPDbyURp",
  options: {
    lead_time_mins: 30,
    verify_addresses: true,
    service_levels: ["same_day", "next_day"],
  },
};

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

const delivery = response.data;

Update Delivery

This endpoint enables you to update various aspects of an existing delivery including tracking information, associated metadata, coordinates and status of the delivery which will typically send notifications to the sender and recipient, depending on what notifications they have enabled.

POST

`/v1/deliveries/:delivery`

Request Parameters

Path Parameters

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

Request Body

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

        {
  // Basic Information
  type: "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,

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

  // Tracking Update
  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

        const body = {
  estimated_delivery_at: "2025-02-22T15:00:00Z",
  pickup_at: "2025-03-22T15:00:00Z",
  coordinates = [32.7520049, -117.224728]
};

const response = await fetch(`https://api.packagex.io/v1/deliveries/${delivery_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 delivery = response.data;

Reference Numbers update

        const body = {
  rma_number: "99995678",
  invoice_number: "4433221234",
  order_number: "55321543",
  purchase_order: "77777567",
  reference_number: "888845",
  account_id: "684685165",
};

const response = await fetch(`https://api.packagex.io/v1/deliveries/${delivery_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 delivery = response.data;

Tracking Information update

        const body = {
  tracking_number: "1Z999999999999999",
  provider_id: "ups",
  service_level_id: "same_day"
};

const response = await fetch(`https://api.packagex.io/v1/deliveries/${delivery_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 delivery = response.data;

Additional Information update

        const body = {
  notes: "Delivered to storage location",
  tags: ["dry_cleaning", "confidential", "fragile"],
  weight: 70,
  metadata: {
    Category: "Large"
  }
};

const response = await fetch(`https://api.packagex.io/v1/deliveries/${delivery_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 delivery = response.data;

Tracking Update Example

        const body = {
  tracking_update: {
    container_id: "ctnr_abc123xyz",
    status: "in_transit",
    location_id: "loc_abc123xyz",
    layout_id: "lay_abc123xyz",
    contact_id: "ctct_abc123xyz",
    user_id: "user_abc123xyz",
    comment: "Package picked up from sender",
    address: "2825 S Glenstone Ave Ste H10, Springfield, MO 65804, US",
    images: ["https://example.com/image1.jpg"]
  }
};

const response = await fetch(`https://api.packagex.io/v1/deliveries/${delivery_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 delivery = response.data;

Update Restrictions

Status Update Restrictions
- Must provide valid status transitions
- Location and layout must be compatible

Create and Update Deliveries

# Create Delivery

# Required Fields

# Request Body Structure

# Address Handling

# Additional Request Body

# Update Delivery

# Request Parameters

# Path Parameters

# Request Body

# Request Examples

# Basic Information Update

# Reference Numbers update

# Tracking Information update

# Additional Information update

# Tracking Update Example

# Update Restrictions

On this page