A Technical Perspective on the Postmates API

December 10, 2014

Share on FacebookShare on TwitterShare on LinkedIn

A Technical Perspective on the Postmates API

Today, we’re releasing the first version of our Postmates Delivery API. Using our API, you can connect your software to the real world in a way that simply hasn’t been possible before. With a few simple HTTP requests our on-demand fleet of couriers will move your items around your city.

To give you an idea of what’s possible with this new API, we’re going to walk you through a very simple imaginary application. If you want to skip ahead, go ahead and jump to our developer site and get signed up: https://postmates.com/developer

Let’s imagine you want to build a web application called ‘Puppies On-Demand’. No, of course you can’t use Postmates to send live animals around the city, but you can send stuffed animals.

Customers are going to come to your website, select a stuffed animal puppy from your inventory, fill out their payment information and enter a delivery address. Even before you accept their order, you’ll want to start using our API.

After you’ve signed up with our developer program, you’ll be given two important pieces of information:

1. Customer ID: cus_abc123 
 2. API Key: fake-api-token-4-u

You’ll use both of these to construct HTTP requests to interact with our API.

The first thing you’ll want to do for your customer above is verify that we can do the delivery. To get a Delivery Quote, you’ll simply provide the pickup and dropoff addresses to our API:

curl -u fake-api-token-4-u: \
-d "dropoff_address=20 McAllister St, San Francisco, CA 94102" \
-d "pickup_address=101 Market St, San Francisco, CA 94105" \
-X POST https://api.postmates.com/v1/customers/cus_abc123/delivery_quotes

You’ll get a reply, formatted in JSON:

kind: "delivery_quote",
id: "dqt_K7SCxZJzteH9R",
created: "2014-12-10T10:04:03Z",
expires: "2014-12-10T10:09:03Z",
fee: 799,
currency: "usd",
dropoff_eta: "2014-12-10T11:15:03Z",
duration: 60

What you’re looking for in this response (beyond simply the fact that it succeeded) is the cost and duration. These values will vary depending on the demand our fleet is experiencing.

For our application, there is no price too high and no wait too long for our customers to get a stuffed puppy. So we’re going to tell our customers we can deliver them a puppy in 60 minutes for $29.95. Once we’ve charged our customer’s credit card, we can submit the delivery to the Postmates API.

curl -u fake-api-token-4-u: \
-d "manifest=1 Stuffed Puppy" \
-d "pickup_name=Puppies On-Demand" \
-d "pickup_address=101 Market St, San Francisco, CA 94105" \
-d "pickup_phone_number=555-555-5555" \
-d "pickup_notes=Just come inside, give us order #123" \
-d "dropoff_name=Alice Customer" \
-d "dropoff_address=20 McAllister St, San Francisco, CA 94102" \
-d "dropoff_phone_number=415-555-5555" \
-d "quote_id=dqt_K7SCxZJzteH9R-" \
-X POST https://api.postmates.com/v1/customers/cus_abc123/deliveries

You should get a delivery object as a response:

"id": "del_K7SD1dUd5aqLU-"
"kind": "delivery",
"live_mode": false,
"status": "pending",
"complete": false,
"updated": "2014-12-09T19:31:22Z",
"fee": 799,
"currency": "usd",
"quote_id": "dqt_K7SCxZJzteH9R-",
"courier": null,
"created": "2014-12-09T19:31:22Z",
"manifest": {
"description": "1 Stuffed Puppy"
"pickup": {
"phone_number": "555-555-5555",
"notes": "Just come inside, give us order #123",
"location": {
"lat": 37.7930812,
"lng": -122.395944
"name": "Puppies On-Demand",
"address": "101 Market Street"
"dropoff": {
"phone_number": "415-555-5555",
"notes": "",
"location": {
"lat": 37.7811372,
"lng": -122.4123037
"name": "Alice Customer",
"address": "20 McAllister Street"
"dropoff_deadline": "2014-12-09T20:31:22Z",
"pickup_eta": null,
"dropoff_eta": null,

As your delivery progresses, you’ll want to refresh this information. Maybe you want to provide a real-time display for your customers so they can see the delivery arrive. You’ll poll the delivery for updates:

curl -u fake-api-token-4-u: \

Some values you’ll want to watch:

  • status: Will move from “pending” to “pickup”, “dropoff” then “delivered”
  • complete: Will be false as long as there are more updates. Great for looping.
  • courier: Will contain the name, image and location of the courier while they are working on the delivery.
  • pickup_eta/dropoff_eta: Gives an estimate of arriving at the pickup location and dropoff location. You might use this to send notifications to your customer when the courier is arriving, or notifying the warehouse to unlock the door.

That’s the Postmates Delivery API. Simple, but oh so powerful. We’re excited to see what sorts of creative uses you can come up with — whether it’s building great new businesses on top of our world-class logistics platform, or just fun hacks to surprise your friends with stuffed puppies.

Stay tuned for exciting new updates as we continue to expand the API and don’t hesitate to share your own ideas for how we can improve.

Visit the Developer Site to learn more.

Rhett Garber is an Engineering Lead at Postmates.