# static buy(delivery_id, rate_id, optionsopt) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 249

Example

//assuming we already created the delivery, we have access to the rates array, if any were returned
//we can pass back the id of the rate that we want to purchase the delivery

const delivery = response.data
const rate = delivery.rates[0].id //selected the first rate
const response = await dispatch.deliveries.buy(delivery.id, rate.id)

//if the purchase was successful, the purchased rate will be available on the purchased_rate property
const purchasedRate = response.data.purchased_rate

# static create(sender, recipient, parcels, optionsopt) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 104

Examples

//This is a basic example for a standard shipment creating without additional options.

const sender = {
   name: "Dispatch Roasters"
   email: roasters@getdispatch.app,
   phone: "4844836699",
   location_id: "loc_j83498fhweofh4937fh"
}

const recipient = {
   name: "Jamie Jones"
   email: jamie.jones@getdispatch.app,
   phone: "4844836699",
   address: {
       address_line1: "500 7th Ave",
       city: "New York",
       state: "NY"
       zipcode: "10018"
   }
}

const parcel = {
   length: 10 // inches
   width: 10 // inches
   height: 10 // inches
   weight: 10 // pounds
   item_description: "Coffee", //optional
   special_handling: "Fragile" //optional
}

//options are completely optional. You can omit the whole object
//or any properties from the object
const options = {
   checkout_total: 5000, //$50.00
   verify_address: false,
   metadata: {
       my_custom_id: "123456789"
   }
}



const response = await dispatch.deliveries.create(sender, recipient, [parcel], options)
const delivery = response.data //this will have the delivery object

//in this example, we'll create the same shipment but add additional options

const sender = {
   name: "Dispatch Roasters"
   email: roasters@getdispatch.app,
   location_id: "loc_j83498fhweofh4937fh"
}

const recipient = {
   name: "Jamie Jones"
   email: jamie.jones@getdispatch.app,
   address: {
       address_line1: "500 7th Ave",
       city: "New York",
       state: "NY"
       zipcode: "10018"
   }
}

const parcel = {
   length: 10 // inches
   width: 10 // inches
   height: 10 // inches
   weight: 10 // pounds
}

//if you wanted to add options, like the checkout_total, you can do so in the fourth argument
const options = {

   //the checkout total is used to return free shipping options. These settings
   //are configured once on the Dispatch dashboard
   checkout_total: 10000 //this would be $100.00 since values are stored as integers


   //the metadata allowed you to add custom properties to the delivery object
   //most often used for an order number or customer number to be able to match
   //delivery with your internal database later. The metadata property will be
   //available on the delivery object when you retrieve it
   metadata: {
       customer_id: 123456789,
       order_id: 987654321
       temp_value: null //passing null will delete the key, if you had one saved before
   }
}


dispatch.deliveries.create(sender, recipient, [parcel], options).then((response) => {
   const delivery = response.data
   console.log(delivery.metadata)

   //handle post delivery creation operations...
}).catch((err) => {
   console.error(err)

   //handle errors...
})

# static list(options) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 64

Example

const response = await dispatch.deliveries.list()
const deliveries = response.data //this will have an array of delivery objects

//check if there are more values in the database
if (data.pagination.has_more) {
   //the delivery objects have a lot of data and setting the pagination to a loop can really hurt performance
   //it's advised to just query in pages
   //io query for the next page of deliveries you could do something like:

   const nextResponse = dispatch.deliveries.list({limit: response.pagination.limit, page: response.pagination.current_page + 1})
}

# static refund(delivery_id) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 288

Example

//a refund can only be done on a purchased label that has not been used
//refunds for on demand couriers need to happen within 5 minutes

const response = await dispatch.deliveries.refund("del_28374n8iudshf3nqifub")

# static retrieve(id) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 38

Example

const response = await dispatch.deliveries.retrieve("del_fjdsklfju8jisjfdisoiu89j")
const delivery = response.data //this will contain the delivery object

# static update(delivery_id, updateopt) → {Promise.<Response>}

Parameters:

View Source dispatch.js, line 319

Example

// you can update emails, names, phone numbers, and metadata for the delivery
// if you want to update the delivery address you will have to create a new delivery.

const update = {
   sender: {
      name: "Dispatch Brewery",
      email: "brewery@getdispatch.app",
      phone: "1234567890"
   },
   recipient: {
      phone: "1234567890" //only want to update the phone number for the recipient
   },
   options: {
      // Metadata is optional information that you can attach to a delivery
      metadata: {
         timestamp: new Date(Date.now()),
         updated_by: "Server Admin"
      }
   }
}

const response = await dispatch.deliveries.update("del_28374n8iudshf3nqifub", update)