One moment while we take you to your dashboard...

Postmates API

Using the Postmates Delivery API, developers can integrate our on-demand local delivery platform into their applications. The API is designed to allow application developers to check prices, schedules, book a delivery, then follow updates on that delivery till completion.

Overview

To get started using the Postmates Delivery API:

What can the API do?

You can use the Postmates API to utilize our fleet of couriers to deliver your products within our geographic zones.

Here is the flow of events that developers most commonly follow when using our API:

  • To see if a delivery is possible, request a delivery quote. This endpoint takes in two addresses and returns a fee, ETA, and other information about a potential delivery.
  • After you have evaluated whether the quoted price and delivery estimate meets your needs, you can create a delivery.
  • While a delivery is in progress, you can track its status in real-time in the developer dashboard, by polling the API, or with webhooks.

What can be delivered using the API?

You can use the Postmates API to deliver most items that can be carried by an average person, including alcohol. Please see our Shipping Policy & Terms of Service for more information on what can and can not be delivered on our platform.

Authentication

The Postmates API requires authentication by HTTP Basic Auth headers. Your API key should be included as the username. The password should be left empty.

The actual header that is used will be a base64-encoded string like this:

Basic Y2YyZjJkNmQtYTMxNC00NGE4LWI2MDAtNTA1M2MwYWYzMTY1Og==

Most of the endpoints provided in the Postmates API are in relation to a specific customer. You'll need to provide your customer id and include it in the URL.

Requests

The base URL for all requests to the Postmates API is:

https://api.postmates.com/

Our API is REST-based. This means:

  • It make use of standard HTTP verbs like GET, POST, DELETE.
  • The API uses standard HTTP error responses to describe errors.
  • Authentication is specified with HTTP Basic Authentication.

All requests use standard query encoding.

POST data should be encoded as standard application/x-www-form-urlencoded.

Rate Limiting

There is a global rate limit for API requests.

Environment Requests/minute
Sandbox 50
Production 1000

Exceeding this rate limit will result in a 429 response.

Versioning

Versioning allows us to provide developers a consistent experience. We provide two levels of versioning:

  • Resource: All endpoints are prefixed with a version such as /v1. This version refers to the overall layout of the endpoints and response standards.
  • Client: Developers can ensure consistent fields and formats by specifying a version as a HTTP header.
    • X-Postmates-Version header such as X-Postmates-Version: 20140825

Addresses

Please format pickup and dropoff addresses this way:

Street Address, City, State, Zip

Any other information, like apartment number, door codes, "care of" instructions, should all be added to pickup or dropoff notes fields. Any extra information included may result in a malformed address, and our geocoder will not be able to find the location.

Responses

The Postmates API uses HTTP status codes to indicate the status of your requests. This includes successful and unsuccessful responses.

All responses are in JSON.

Status Codes

  • 200 - OK: Everything went as planned.
  • 304 - Not Modified: Resource hasn't been updated since the date provided. See Caching below.
  • 400 - Bad Request: You did something wrong. Often a missing argument or parameter.
  • 401 - Unauthorized: Authentication was incorrect.
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error: We had a problem processing the request.
  • 503 - Service Unavailable: Try again later.

Errors

Error responses include details about what went wrong.

{
  "kind": "error",
  "code": "invalid_params",
  "message": "The parameters of your request were invalid.",
  "params": {
    "dropoff_name": "Dropoff name is required.",
    "dropoff_phone_number": "Dropoff phone number must be valid phone number."
  }
}

Error Codes

This list will likely become more comprehensive as features are implemented.

  • invalid_params - The indicated parameters were missing or invalid.
  • unknown_location - We weren't able to understand the provided address. This usually indicates the address is wrong, or perhaps not exact enough.
  • rate_limit_exceeded - This API key has made too many requests.
  • customer_not_approved - You account has not been approved to create deliveries. Please refer to our approval guidelines for more information.
  • account_suspended
  • not_found
  • service_unavailable
  • delivery_limit_exceeded - You have hit the maximum amount of ongoing deliveries allowed.
  • customer_limited - Your account's limits have been exceeded.
  • couriers_busy - All of our couriers are currently busy.

Types

Responses often indicate a type of object being described. Though this can often be inferred from the resource being requested, but we like to be explicit:

{
  kind: "user",
  name: "Alice"
}

Some responses might include a list of objects:

{
  kind: "list",
  data: [
    {
      kind: "user",
      name: "Alice"
    },
    {
      kind: "user",
      name: "Bob"
    }
  ]
}

Currency

When a response involves a currency, it is described as follows:

{
  amount: 799,
  currency: "usd"
}

This indicates a value of $7.99 in USD.

Times

Times are formatted according to ISO8601 and reported only in UTC time. For example:

{
  created: "2014-08-26T10:04:03Z",
}

Objects will often have attributes like "created" and "updated".

Large Result Sets

Some resources may have too many objects to include in a single response. To support pagination, we include attributes such as:

{
  total_count: 100,
  next_href: "https://api.postmates.com/v1/...",
  data: [...]
}

By requesting the next_href, the client will receive the next set of objects.

Clients can also request a specific number of response objects by using the limit query parameter.

Locations

Some objects have a geographic location associated with them. This typically of the form:

{
  "location" : {
    "lat" : 37.42291810,
    "lng" : -122.08542120
  }
}

Webhooks

Webhooks allow you to receive real-time updates to your ongoing deliveries. By configuring a URL we can POST updates to, you'll get the most up-to-date information to show to your customers.

Webhook Endpoint

To use webhooks, you'll need to configure your own web application to accept HTTP POST requests from us. These requests will contain JSON objects representing the event that has occurred.

Configure this URL endpoint in the developer dashboard. You can choose live or test mode.

The Event Object

Event objects follow a standard format. Each event has:

  • A kind to indicate what type of event has been provided.
  • A unique id for this event instance.
  • A flag indicating if the event applies to live_mode data.
  • Timestamp indicating when the event was generated.
  • One or more fields specific to each sub-type.
  • The id of the object the event applies to (example: delivery_id).
  • An updated version of the object the event applies to. For example, all delivery events will include a full delivery object as the data field.
{
  "kind": "event.delivery_status",
  "id": "evt_KC9LLdlTwr7udF",
  "delivery_id": "del_3vDjjkd21b",
  "status": "pickup",
  "data": {
    "kind": "delivery",
    "id": "del_3vDjjkd21b",
    "status": "pickup",
    ...
  },
  "created": "2014-08-26T10:04:03Z",
  "live_mode": false
}

Supported Event Types

  • delivery_status - Sent each time the status field on a delivery changes.
    • Event will contain the field status and include an updated delivery object as the data.
  • delivery_deadline - Sent when the delivery deadline for a delivery has changed.
    • Event will contain the field dropoff_deadline and include an updated delivery object as the data.
  • courier_update - Sent periodicially as a courier changes locations.
    • Event will contain the field location with lat and lng fields. An updated delivery object will be included as the data.
  • delivery_return - Sent when a delivery has been returned to pickup location
    • Event will contain the field status and include an updated delivery object as the data.

Versioning

Webhook versioning is based on when you configure the webhook. The version string will be provided along with the webhook request in a X-Postmates-Version HTTP header.

Security

Webhooks created through the Postmates API can be verified by calculating a digital signature.

Each webhook request has a X-Postmates-Signature header which is generated using a shared secret and the payload of the webhook request.

To verify that the request came from Postmates, pass the secret and payload through the SHA-256 hashing algorithm, and make sure it's equal to X-Postmates-Signature.

Here's an example in Python:

>>> import hashlib, hmac
>>> api_secret = 'c5c26d5a-70d6-46c7-a652-d7c09825ad29'
>>> payload = '{"kind": "event.courier_update", "location": {"lat": 37.7974109, "lng": -122.424145}}' # Shortened for this example
>>> hmac.new(api_secret, payload, hashlib.sha256).hexdigest()
'cdff8133fb065f8d37a2c1c94c3331b6a82766d14e7ea4faacc4886558cedd65'

Monitoring

You can monitor webhooks in the Postmates Partner Dashboard. Webhook event logs are saved for 30 days.

Test Mode

For your development convenience, we provide a test mode for our API. Using a test API key will allow you to exercise all the endpoints. We even have a special robot courier named Robo that will deliver your imaginary goods. This courier updates every 10 seconds.

All responses during live mode will have an extra attribute:

{
  "live_mode": true,
}

If you want to play around with our endpoints, you can use Postman:

Events

The delivery create API endpoint has optional post parameters for specifying when various delivery events occur.

  • pickup - When Robo will start moving towards the pickup.
  • pickup_complete - When Robo will have picked up the items.
  • dropoff - When Robo will start moving towards the dropoff.
  • delivered - When Robo will complete the delivery.

Interface

The interface is a key value pair where the event type has a corresponding time which is relative to the creation date of the job. If an event is set to 00:10:00, then Robo will start the event in 10 minutes.

        robo_event="hh:mm:ss"
    
  • hh - hours
  • mm - minutes
  • ss - seconds

Post Example

Here is an example where Robo will start pickup in 10 minutes, pickup_complete in 20 minutes, dropoff in 21 minutes and delivered in 34 minutes.

      POST /v1/customers/:customer_id/deliveries

      manifest="a box of kittens"
      manifest_reference="Optional reference that identifies the box of kittens"
      pickup_name="The Warehouse"
      pickup_address="20 McAllister St, San Francisco, CA"
      pickup_phone_number="555-555-5555"
      pickup_business_name="Optional Pickup Business Name, Inc."
      pickup_notes="Optional note that this is Invoice #123"
      dropoff_name="Alice"
      dropoff_address="101 Market St, San Francisco, CA"
      dropoff_phone_number="415-555-1234"
      dropoff_business_name="Optional Dropoff Business Name, Inc."
      dropoff_notes="Optional note to ring the bell"
      robo_pickup="00:10:00"
      robo_pickup_complete="00:20:00"
      robo_dropoff="00:21:00"
      robo_delivered="00:34:00"
    

Pathing

Pathing on Robo is as the crow flies between its location and either its pickup or dropoff point depending on the job state. The rate in which Robo moves is based on the when the next event occurs. For example, if pickup is at 00:00:00 and pickup_complete is at 00:10:00 then the rate is the distance between Robo's current location divided by 10 minutes.

Invalid Event Configurations

Delivery states happen in order so if the event configuration does not respect this order then the event configuration is ignored.

How do I get a production key?

When you're ready to start doing live deliveries, update your payment details and use your production API key.