1. Deliveries
  2. Write Deliveries

Deliveries

Write Deliveries

As a shipping provider, a delivery is the representation of one ot more parcels that you are delivering to a recipient. Often deliveries are created for you when a sender, including yourself, creates a shipment.

You can, however, create a delivery manually which will also create a complimentary shipment for the sender.

As the 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`

Addresses

When you provide an address for the sender and recipient, you have a few options:

  • Provide the full address as a string in the address property. If there is a unit number in the address and you collected it separately, you can provide that via the address_line2 property.
  • Provide the address as an object with the following properties
    • line1
    • line2 (optional)
    • city
    • state
    • postal_code
    • country (optional)
  • Provide a PackageX address ID in the address property. PackageX address IDs are prefixed with addr_
  • Provide a PackageX location ID in the location_id property. PackageX location IDs are prefixed with loc_
js 
        const parcel = {
  length: 5,
  width: 5,
  height: 5,
  weight: 2,
  inventory: [
    {
      name: "Dispatch Roasters Tequila",
    },
    {
      name: "Dispatch Roasters Coffee",
      vendor: "Dispatch, Inc",
      origin_country: "Ethiopia",
    },
  ],
};

const data = {
  sender: {
    name: "Jamie Jones",
    email: "jamie@packagex.io",
    phone: "4844836699",
    address: "500 7th ave, New York, NY, 10018",
    address_line2: "Floor 10",
  },
  recipient: {
    name: "Ashley Yound",
    email: "ashley@packagex.io",
    phone: "4844836699",
    address: "3 Brewster Rd, Newark, NJ, 07114",
  },
  parcels: [parcel],
  location_id: "loc_czhgjrk5JaVvyATPDbyURp",
};

const res = 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(data),
}).then((res) => res.json());

const delivery = res.data;

Once the delivery has been created, you're able to update the status and location of the delivery. Notifications and webhooks will be sent to the sender and recipient as the delivery progresses.

When creating the delivery, you can additionally specify whether it is inbound or outbound by adding the following optional property in the request body (defaults to outbound):

  • type "outbound" | "inbound"

Update Delivery

POST
`/v1/deliveries/:delivery`

When you are ready to update a delivery, you can update the status of the delivery which will typically send notifications to the sender and recipient, depending on what notifications they have enabled. You can also update the coordinates of the delivery without updating the status for a better user experience.

Update Status

js 
        const data = {
  tracking_update: {
    //Most provider just add the city, state, and postal code.
    //You don't need to provide an address if you will be sending coordinates
    address: {
      city: "San Diego",
      state: "California",
    },
    status: "out_for_delivery",
    comment: "Should be coming in 5 mins", //This is optional
    images: [], //An array of base64 images
    tracking_number: "PKGX-1234567-ABCDEFG", //Only required if there are multiple parcels in the delivery
  },
};

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(data),
});

Update Coordinates

You can update the coordinates for the delivery at any time. This will not create a tracking update but can be used to show the live location on a map.

js 
        const data = {
  coordinates: [40.7531386, -73.9894616],
};

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(data),
}).then((res) => res.json());

const delivery = response.data;

Update Delivery Date & Time

You may also want to update the estimated delivery date and time for the delivery - especially as the delivery date approaches.

You can submit the estimated delivery date and time in the following formats:

  • ISO Date string
  • JS Date object
  • Seconds from epoch
  • Milliseconds from epoch
js 
        const data = {
  estimated_delivery_at: new Date(Date.now() + 1000 * 60 * 30), //30 minutes from now
};

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(data),
}).then((res) => res.json());

const delivery = response.data;

Update Delivery Type

You may also want to update the delivery type from outbound to inbound or vice versa.

js 
        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({type: "inbound"}),
}).then((res) => res.json());

const delivery = response.data;

Previous <- Retrieve Deliveries
Next Inferences Overview ->