Scope and Summary

This API specification defines how delivery.com will place delivery requests to authorized Last Mile
Providers. For all cases the delivery requests are made for ASAP service (i.e pickup expected under 45 minutes) in the United States.

To become an authorized last mile provider, send us an inquiry at lmp-api@delivery.com.

Currently our API supports the following calls and responses. Each endpoint will be a URL provided to us by you, the last mile provider. When you become an authorized last mile provider, we’ll ask for these URLs :

Endpoint Description
delivery estimate a POST call made by delivery.com to the Last Mile Provider with detailed delivery parameters. Last mile provider is expected to respond with estimated price and pickup time estimates.
book delivery a POST call made by delivery.com to the Last Mile Provider to book a delivery. This call comes after the “get delivery estimate” call.
get delivery status a GET call made by delivery.com to the Last Mile Provider get the delivery status details.
cancel delivery a POST call made by delivery.com to Last Mile Provider to cancel a previously booked delivery.

NB: All endpoints can return a 401 unauthorized as well as a 500 fatal. And lastly, all requests below are from delivery.com to you. To signify everything was processed correctly on your end, return a 200. To signify an error, return anything other than 200.

Delivery estimate

Request

delivery.com will make a POST request to whatever URL you provide us when signing up.

Parameters

Parameters Values Description
pickup Object pickup location
pickup.address String address for pickup(#, street)
pickup.apt String (optional) apartment, suite, unit or floor #
pickup.city String city
pickup.state String state abbreviation such (i.e. NY/CA/DC…)
pickup.zip String zip code
pickup.latitude Float latitude
pickup.longitude Float longitude
delivery Object delivery location
delivery.address String address for delivery(#, street)
delivery.apt String (optional) apartment, suite, unit or floor #
delivery.city String city
delivery.state String state abbreviation such (i.e. NY/CA/DC…)
delivery.zip String zip code
delivery.latitude Float latitude
delivery.longitude Float longitude
gratuity Float 3.50

Sample

{
  "pickup": {
    "address": "2 clinton st",
    "apt": null,
    "city": "nyc",
    "state": "ny",
    "zip": "10002",
    "latitude" : 40.706868,
    "longitude" : -74.004365
  },
  "delivery": {
    "address": "310 e 3nd st",
    "apt": "3d",
    "city": "nyc",
    "state": "ny",
    "zip": "10009",
    "latitude" : 40.720345,
    "longitude" : -73.978848
  },
  "gratuity" : 3.50
}

Response

Parameters

Parameter Type Description
estimate_id String estimate unique id for the Last Mile Provider
estimated_at Integer time delivery estimate is provided – Unix Timestamp
estimate_valid_until Integer time delivery estimate valid until – Unix Timestamp
pickup_eta Integer estimated time to pickup – Unix Timestamp
delivery_eta Integer estimated time to delivery – Unix Timestamp
price Float estimated price of the delivery – in USD

Sample

{
  "estimate_id": "123AF019",
  "estimated_at": 1437401048,
  "estimate_valid_until": 1437402300,
  "pickup_eta": 1437401959,
  "delivery_eta": 1437403560,
  "price": 6.5
}

Errors

HTTP 400 Bad Request

{
  "code": "400",
  "user_msg": "null is not a valid last mile provider name",
  "dev_msg": ""
}

HTTP 401 Unauthorized
HTTP 500 Fatal Error

Book Delivery

Request

delivery.com will book a previously estimated delivery from the Last Mile Provider by making a POST request to whatever URL you provide us when signing up.

Parameters

Parameters Values Description
estimate_id String estimate unique id for the Last Mile Provider
order_id String delivery.com unique order id
items Object list of items for the delivery order
items.name String item name
items.quantity Integer item quantity
pickup Object pickup information
pickup.location Object pickup location
pickup.location.address String address for pickup(#,street)
pickup.location.apt String (optional) apartment, suite, unit or floor #
pickup.location.city String city
pickup.location.state String state abbreviation such (i.e. NY/CA/DC…)
pickup.location.zip String zip code
pickup.location.latitude Float latitude
pickup.location.longitude Float longitude
pickup.contact Object pickup contact for order
pickup.contact.merchant_name String merchant name
pickup.contact.email String merchant email
pickup.contact.phone String merchant phone
pickup.instructions String instructions for pickup
delivery Object delivery information
delivery.location Object delivery location
delivery.location.address String address for pickup(#,street)
delivery.location.apt String (optional) apartment, suite, unit or floor #
delivery.location.city String city
delivery.location.state String state abbreviation such (i.e. NY/CA/DC…)
delivery.location.zip String zip code
delivery.location.latitude Float latitude
delivery.location.longitude Float longitude
delivery.contact Object delivery contact for order
delivery.contact.first_name String customer first name
delivery.contact.last_name String customer last name
delivery.contact.company_name String (optional) company name
delivery.contact.email String customer email
delivery.contact.phone String customer phone
delivery.instructions String instructions for delivery

Sample

{
  "estimate_id": "123AF019",
  "order_id": "1233434",
  "items": [
    {
      "name": "Chicken Sandwich",
      "quantity": 1
    },
    {
      "name": "Coke",
      "quantity": 1
    }
  ],
  "pickup": {
    "location": {
      "address": "2 clinton st",
      "apt": null,
      "city": "new york",
      "state": "ny",
      "zip": "10002",
      "latitude" : 40.720345,
      "longitude" : -73.978848
    },
    "contact": {
      "merchant_name": "Merchant XYZ",
      "email": "merchantxyz@delivery.com",
      "phone": "5553450123"
    },
    "instructions": "NA"
  },
  "delivery": {
    "location": {
      "address": "310 east 2nd st",
      "apt": "6",
      "city": "new york",
      "state": "ny",
      "zip": "10009",
      "latitude" : 40.706868,
      "longitude" : -74.004365
    },
    "contact": {
      "first_name": "john",
      "last_name": "smith",
      "company_name": null,
      "email": "jsmith@delivery.com",
      "phone": "5554450123"
    },
    "instructions": "please wait after ringing, I need to come down to open the building door"
  }
}

Response

Parameters

Parameters Values Description
delivery_id String delivery unique id for the Last Mile Provider
estimate_id String estimate unique id for the Last Mile Provider
order_id String delivery.com unique order id
booked_at Integer time delivery is created – Unix Timestamp
price Float estimated price of the delivery – in USD
status Enum See Delivery Status descriptions below
items Object list of items for the delivery order
items.name String item name
items.quantity Integer item quantity
pickup Object pickup information
pickup.location Object pickup location
pickup.location.address String address for pickup(#,street)
pickup.location.apt String (optional) apartment, suite, unit or floor #
pickup.location.city String city
pickup.location.state String state abbreviation such (i.e. NY/CA/DC…)
pickup.location.zip String zip code
pickup.location.latitude Float latitude
pickup.location.longitude Float longitude
pickup.contact Object pickup contact for order
pickup.contact.merchant_name String merchant name
pickup.contact.email String merchant email
pickup.contact.phone String merchant phone
pickup.instructions String instructions for pickup
pickup.eta Integer estimated time to pickup – Unix Timestamp
delivery Object delivery information
delivery.location Object delivery location
delivery.location.address String address for pickup(#,street)
delivery.location.apt String (optional) apartment, suite, unit or floor #
delivery.location.city String city
delivery.location.state String state abbreviation such (i.e. NY/CA/DC…)
delivery.location.zip String zip code
delivery.location.latitude Float latitude
delivery.location.longitude Float longitude
delivery.contact Object delivery contact for order
delivery.contact.first_name String customer first name
delivery.contact.last_name String customer last name
delivery.contact.company_name String (optional) company name
delivery.contact.email String customer email
delivery.contact.phone String customer phone
delivery.instructions String instructions for delivery
delivery.eta Integer estimated time to delivery – Unix Timestamp

Sample

{
  "delivery_id":"1234234",
  "booked_at":2342342354234532,
  "estimate_id": "123AF019",
  "order_id": "1233434",
  "status":"booked",
  "items": [
    {
      "name": "Chicken Sandwich",
      "quantity": 1
    },
    {
      "name": "Coke",
      "quantity": 1
    }
  ],
  "pickup": {
    "location": {
      "address": "2 clinton st",
      "apt": null,
      "city": "new york",
      "state": "ny",
      "zip": "10002",
      "latitude" : 40.706868,
      "longitude" : -74.00436
    },
    "contact": {
      "merchant_name": "Merchant XYZ",
      "email": "merchantxyz@delivery.com",
      "phone": "5553450123"
    },
    "instructions": "NA",
    "eta":2342343
  },
  "delivery": {
    "location": {
      "address": "310 east 2nd st",
      "apt": "6",
      "city": "new york",
      "state": "ny",
      "zip": "10009",
      "latitude" : 40.720345,
      "longitude" : -73.978848
    },
    "contact": {
      "first_name": "john",
      "last_name": "smith",
      "company_name": null,
      "email": "jsmith@delivery.com",
      "phone": "5554450123"
    },
    "instructions": "please wait after ringing, I need to come down to open the building door",
    "eta" : 234235345
  }
}

Errors

HTTP 400 Bad Request

{
  "code": "400",
  "user_msg": "null is not a valid last mile provider name",
  "dev_msg": ""
}

HTTP 401 Unauthorized
HTTP 500 Fatal Error

Delivery Status

Request

delivery.com will request a status update from the Last Mile Provider for an ongoing delivery by making a GET request to whatever URL you provide us when signing up, except with one caveat : we’ll append ‘/{delivery_id}’ to the URL. So if the URL provided was ‘http://example.com/status’ then we’ll make a GET request to ‘http://example.com/status/12334′ for a delivery_id of ’12334′.

Parameters

Parameters Values Description
delivery_id String delivery unique id from the Last Mile Provider

Sample

GET http://example.com/status/12334

Response

Parameters

Parameters Values Description
delivery_id String delivery unique id for the Last Mile Provider
estimate_id String estimate unique id for the Last Mile Provider
order_id String delivery.com unique order id
booked_at Integer time delivery is created – Unix Timestamp
status_time Integer time of status update provided – Unix Timestamp
price Float estimated price of the delivery – in USD
status Enum See Delivery Status descriptions below
courier Object details about courier in charge of the delivery
courier.first_name String courier first name
courier.last_name String courier last name
courier.phone String courier phone number
courier.location Object location of the courier
courier.location.latitude Float courier’s latitude
courier.location.longitude Float courier’s longitude
items Object list of items for the delivery order
items.name String item name
items.quantity Integer item quantity
pickup Object pickup information
pickup.location Object pickup location
pickup.location.address String address for pickup(#,street)
pickup.location.apt String (optional) apartment, suite, unit or floor #
pickup.location.city String city
pickup.location.state String state abbreviation such (i.e. NY/CA/DC…)
pickup.location.zip String zip code
pickup.location.latitude Float latitude
pickup.location.longitude Float longitude
pickup.contact Object pickup contact for order
pickup.contact.merchant_name String merchant name
pickup.contact.email String merchant email
pickup.contact.phone String merchant phone
pickup.instructions String instructions for pickup
pickup.eta Integer estimated time to pickup – Unix Timestamp
delivery Object delivery information
delivery.location Object delivery location
delivery.location.address String address for pickup(#,street)
delivery.location.apt String (optional) apartment, suite, unit or floor #
delivery.location.city String city
delivery.location.state String state abbreviation such (i.e. NY/CA/DC…)
delivery.location.zip String zip code
delivery.location.latitude Float latitude
delivery.location.longitude Float longitude
delivery.contact Object delivery contact for order
delivery.contact.first_name String customer first name
delivery.contact.last_name String customer last name
delivery.contact.company_name String (optional) company name
delivery.contact.email String customer email
delivery.contact.phone String customer phone
delivery.instructions String instructions for delivery
delivery.eta Integer estimated time to delivery – Unix Timestamp

Sample

{
  "delivery_id":"1234234",
  "booked_at":2342342354234532,
  "estimate_id": "123AF019",
  "status_time" : 2342342354234532,
  "price" : 5.50,
  "order_id": "1233434",
  "status":"to_pickup",
  "courier": 
    {
      "first_name": "John",
      "last_name": "Smith",
      "phone": "5553232323",
      "location": 
        { 
           "latitude" : 72.2343234,
           "longitude" : -12.3234,
        }
    },
  "items": [
    {
      "name": "Chicken Sandwich",
      "quantity": 1
    },
    {
      "name": "Coke",
      "quantity": 1
    }
  ],
  "pickup": {
    "location": {
      "address": "2 clinton st",
      "apt": null,
      "city": "new york",
      "state": "ny",
      "zip": "10002",
      "latitude" : 40.706868,
     "longitude" : -74.004365
    },
    "contact": {
      "merchant_name": "Merchant XYZ",
      "email": "merchantxyz@delivery.com",
      "phone": "5553450123"
    },
    "instructions": "NA",
    "eta":2342343,
  },
  "delivery": {
    "location": {
      "address": "310 east 2nd st",
      "apt": "6",
      "city": "new york",
      "state": "ny",
      "zip": "10009",
      "latitude" : 40.720345,
      "longitude" : -73.978848
    },
    "contact": {
      "first_name": "john",
      "last_name": "smith",
      "company_name": null,
      "email": "jsmith@delivery.com",
      "phone": "5554450123"
    },
    "instructions": "please wait after ringing, I need to come down to open the building door",
    "eta" : 234235345
  }
}

Errors

HTTP 400 Bad Request

{
  "code": "400",
  "user_msg": "null is not a valid last mile provider name",
  "dev_msg": ""
}

HTTP 401 Unauthorized
HTTP 500 Fatal Error

Cancel Delivery

Request

delivery.com will cancel an ongoing delivery by the Last Mile Provider by making a POST request to whatever URL you provide us when signing up, except with one caveat : we’ll append ‘/{delivery_id}’ to the URL. So if the URL provided was ‘http://example.com/cancel’ then we’ll make a POST request to ‘http://example.com/cancel/12334′ for a delivery_id of ’12334′.

Parameters

Parameters Values Description
delivery_id String delivery unique id from the Last Mile Provider

Sample

POST http://example.com/cancel/12334

Response

HTTP 200 OK

Errors

HTTP 400 Bad Request

{
  "code": "400",
  "user_msg": "null is not a valid last mile provider name",
  "dev_msg": ""
}

HTTP 401 Unauthorized
HTTP 500 Fatal Error

Delivery Status Descriptions

More details on the different values supported for delivery status

Status Description
booked delivery is successfully created and courier en-route soon
denied delivery request denied (no-driver, available, estimate no more valid…)
to_pickup courier actively on his way to pickup location
at_pickup courier at pickup location
to_delivery courier picked up the order and actively on his way to delivery location
at_delivery courier at delivery location
delivered delivery completed
cancelled delivery cancelled
failed the delivery was not complete because of a merchant or customer facing issue (like merchant is closed or customer is not home)

Testing

After you email lmp-api@delivery.com with the 4 URLs above, we’ll provide you with 4 test endpoints that you can curl in order to instigate a call to your system. For example, you’ll curl a test delivery estimate endpoint we’ll provide you, which will cause delivery.com to POST to your delivery estimate URL.