Nervously Proposing Marriage


    1.1.6 • Public • Published

    Dispatch Sender Node.js Library

    The Dispatch Sender Node library provides convenient access to the Dispatch Sender API for applications written in server-side JavaScript. Detailed documentation can be found here.


    Install the package with:

    npm install dispatch-node --save


    The package needs to be configured with your account's API Key, which is available in the Dispatch Dashboard.

    const Dispatch = require("dispatch-node");
    const dispatch = new Dispatch("key_EHKD5tbatzX59DArnTBjhr46G5n1f4aJkvwPByft");
      .then((response) => console.log(
      .catch((error) => console.error(error));

    Using Promises

    Every method returns a chainable promise which can be used instead of a regular callback:

    // Create a new delivery and then select the cheapest rate to purchase
    const sender = {
      name: "Dispatch Roasters",
      email: "",
      phone: "4844836699",
      location_id: "loc_1uzCQL4cTjjw3vRfE2qYk1",
    const recipient = {
      name: "Jamie Jones",
      email: "",
      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: 5.5, // 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",
      .create(sender, recipient, [parcel], options) //parcel is passed in an array since you can pass multiple parcels as part of one delivery
      .then((response) => {
        const delivery =;
        //your logic to select the rate you want.
        //you could have a customer select it or
        //you can filter by price or service level
        //in this example, we're selecting the first rate
        const rate = delivery.rates[0];
      .then((response) => {
        //new delivery was created
      .catch((err) => {
        //deal with the error

    Delivery Lifecycle

    The label generation process is a multi-step process and understanding how this works will make using the API much easier.

    1. A request is made using the sender, recipient, and parcels fields. Here we are creating a delivery with all of the possible rates from any providers you have enabled on your dashboard.

    2. During this step, the rates are held for 15 minutes. If no rate is purchased during this interval, the delivery will expire. You can of course create a new delivery in this case.

    3. Within these 15 minutes, you can now select one of these rates to buy. The selection process is entirely based on your business logic like displaying options to customers or having your backend decide the best option.

    4. Once the transaction has gone through, the delivery will be populated with the label image url and all other properties you need for tracking.

    5. At this point, if you have made a mistake, you are able to request a refund for a shipping label. You have up to 14 days to request a refund for a traditional carrier. For on-demand couriers, you'll have a 5 minute time window to request a refund.


    From the Dispatch Dashboard you can configure webhooks. There are several webhook statuses you can choose from. Our webhooks expect a response with a status code of 200 within 5 seconds. This should be enough time to process the data and respond back to us. If we do not receive a response back from you within 5 seconds, we'll retry the webhook a second time after waiting for 3 seconds.

    Our webhooks will attempt to POST to your endpoint.

    Event Description
    delivery_created This will fire when the delivery intent was created. This is before the purchase was made
    delivery_canceled This will fire after a delivery was canceled. This is usually due to a refund
    delivery_purchased This webhook will fire after a delivery intent is successfully captured
    tracking_updated This webhook will fire when there are any tracking updates to the package. The tracking updated webhook does not fire when the initial delivery intent is created or purchased.

    Each webhook will contain the entire Delivery object. Most often, you're probably interested in the tracking_updates property which is an ordered array of Tracker objects or the tracking_status property which is the current Tracker object.

    Package Statuses

    Dispatch packages have two "statuses": the status and substatus. The status describes the general concept of what is happening to the package, and the substatus gives you more detail about the package. For example, the status could be in_transit but the substatus will give you details about the transit like out_for_delivery. Internally at Dispatch, we use the substatus field more often. The status and substatus can be found on the Delivery object and the Tracker object.

    Below is the list of statuses that we support. Keep in mind that the Tracker object will always have a human readable message that you can display.

    As we are in beta, there is a chance that some of these statuses will change before we hit V1.

    status substatus is_issue description
    pre_transit created false Package was created
    transit address_issue true Issue with the address
    transit courier_at_sender false Courier arrived to pickup up the package
    transit contact_courier true Courier needs to be contacted
    transit delayed true Package will not get there on time
    transit delivery_attempted true Delivery attempted but not completed
    transit delivery_rescheduled true Delivery rescheduled
    transit delivery_scheduled false Delivery data scheduled
    transit location_inaccessible true Courier could not get to the location
    transit out_for_delivery false Package it out for delivery
    transit package_accepted false Package was accepted. Taken from sender.
    transit package_at_waypoint false Package was accepted by an intermediate location
    transit in_transit false Package is in transit
    transit pickup_available false Pickup available
    transit package_damaged true Package was damaged in transit
    delivered delivered false Package was successfully delivered
    returned return_to_sender true Package was returned
    failed package_undeliverable true Package could not be delivered
    failed package_lost true Package was lost
    canceled canceled true This delivery was canceled. Usually do to a refund
    unknown unknown true Dispatch doesn't know what happened


    npm i dispatch-node

    DownloadsWeekly Downloads






    Unpacked Size

    2.36 MB

    Total Files


    Last publish


    • vpanyushenko
    • vladpasculescu