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

Endpoints

Get a Delivery Quote

The first step in using the Postmates API is get a quote on a delivery. This allows you to make decisions about the appropriate cost and availability for using the Postmates platform, which can vary based on distance and demand.

A Delivery Quote provides an estimate for a potential delivery. This includes the amount the delivery is expected to cost as well as an estimated delivery window. As demand on our platform changes over time, the fee amount and ETA may increase beyond what your use-case can support.

A Delivery Quote can only be used once and is only valid for a limited duration.

Endpoint

POST /v1/customers/:customer_id/delivery_quotes

Query Parameters

Name Description
pickup_address The pickup address for a potential delivery. Example: "20 McAllister St, San Francisco, CA"
dropoff_address The dropoff address for a potential delivery. Example: "101 Market St, San Francisco, CA"

Response

{
  "kind": "delivery_quote",
  "id": "dqt_qUdje83jhdk",
  "created": "2014-08-26T10:04:03Z",
  "expires": "2014-08-26T10:09:03Z",
  "fee": 799,
  "currency": "usd",
  "dropoff_eta": "2014-08-26T12:15:03Z",
  "duration": 60
}
Name Description
fee Amount in cents that will be charged if this delivery is created (see "Other Standards » Currency").
currency Currency the "amount" values are in. (see "Other Standards » Currency").
dropoff_eta Estimated drop-off time. This value may increase to several hours if the postmates platform is in high demand.
duration Estimated minutes for this delivery to reach dropoff, this value can be highly variable based upon the current amount of capacity available.
expires Date/Time after which the quote will no longer be accepted.

Get Delivery Zones

This endpoint returns a list of GeoJSON-valid FeatureCollection objects representing all of our active delivery zones.

Coordinates will be in the format [longitude, latitude].

Our zones are not bound by zip code borders. If you need to check to see if an address is within a given zone, use the Delivery Quote endpoint.

Endpoint

  GET /v1/delivery_zones

Response

[
  {
    "type": "FeatureCollection",
    "properties": {
      "zone_name": "San Francisco",
      "market_name": "San Francisco"
    },
    "features": [
      {
        "type": "Feature",
        "properties": {
          "name": "zone_geometry"
        },
        "geometry": {
          "type": "MultiPolygon",
          "coordinates": [
            [
              [
                [
                  -122.47595358787643,
                  37.8065996742509
                ],
                [
                  -122.51577902732468,
                  37.78435350040903
                ],
                [
                  -122.50135947166052,
                  37.69856171219177
                ],
                [
                  -122.37982321679993,
                  37.70345125656206
                ],
                [
                  -122.35441733301585,
                  37.724092443613486
                ],
                [
                  -122.36883688867101,
                  37.75721495520453
                ],
                [
                  -122.3818831533247,
                  37.78923738069619
                ],
                [
                  -122.40591574608932,
                  37.81365194030545
                ],
                [
                  -122.43338156639815,
                  37.813109482214635
                ],
                [
                  -122.47595358787643,
                  37.8065996742509
                ]
              ]
            ]
          ]
        }
      },
      {
        "type": "Feature",
        "properties": {
          "name": "map_center"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            -122.42629999999998,
            37.773299999999985
          ]
        }
      }
    ]
  },
...
]
Name Description
properties.zone_name The name of the zone.
properties.market_name A market can contain multiple zones.
features[0].geometry A GeoJSON `MultiPolygon` object representing the geometry of a zone.
features[1].geometry A GeoJSON `Point` object representing where to center the map for a given market.

Create a Delivery

After you've successfully created a delivery quote, it's time to create an actual delivery on the Postmates platform. It's recommended that you include the previously generated quote_id to ensure the costs and ETAs are consistent with the quote. Once a delivery is accepted, the delivery fee will be deducted from your account.

Endpoint

POST /v1/customers/:customer_id/deliveries

Query Parameters

Name Description
quote_id The ID of a previously generated delivery quote. Optional, but recommended. Example: "del_KSsT9zJdfV3P9k"
manifest A detailed description of what the courier will be delivering. Example: "A box of gray kittens"
manifest_reference Optional reference that identifies the manifest. Example: "Order #690"
pickup_name Name of the place where the courier will make the pickup. Example: "Kitten Warehouse"
pickup_address The pickup address for the delivery. Example: "20 McAllister St, San Francisco, CA"
pickup_phone_number The phone number of the pickup location. Example: "415-555-4242"
pickup_business_name Optional business name of the pickup location. Example: "Feline Enterprises, Inc."
pickup_notes Additional instructions for the courier at the pickup location. Example: "Ring the doorbell twice, and only delivery the package if a human answers."
dropoff_name Name of the place where the courier will make the dropoff. Example: "Alice"
dropoff_address The dropoff address for the delivery. Example: "678 Green St, San Francisco, CA"
dropoff_phone_number The phone number of the dropoff location. Example: "415-555-8484"
dropoff_business_name Optional business name of the dropoff location. Example: "Alice's Cat Cafe"
dropoff_notes Additional instructions for the courier at the dropoff location. Example: "Tell the security guard that you're here to see Alice."

Response

{
  "kind": "delivery",
  "id": "del_3vDjjkd21b",
  "created": "2014-08-26T10:04:03Z",
  "updated": "2014-08-26T11:21:16Z",
  "status": "pickup",
  "complete": false,
  "pickup_eta": "2014-08-26T10:16:00Z",
  "dropoff_eta": "2014-08-26T10:29:00Z",
  "dropoff_deadline": "2014-08-26T10:45:00Z",
  "quote_id": "dqt_qUdje83jhdk",
  "fee": 799,
  "currency": "usd",
  "manifest": {
    "reference": "SP 937-215"
    "description": "10kg cardboard box",
  },
  "dropoff_identifier": "Picard",
  "pickup": {
    "name": "The Warehouse",
    "phone_number": "5558675309",
    "address": "20 McAllister St, San Francisco, CA 94102",
    "detailed_address": {
      "street_address_1": "20 McAllister St",
      "street_address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94102",
      "country": "US",
    },
    "notes": "Invoice #123",
    "location" : {
        "lat" : 37.781116,
        "lng" : -122.412339
    },
  },
  "dropoff": {
    "name": "Alice Customer"
    "phone_number": "4155555555",
    "address": "101 Market St, San Francisco, CA 94105",
    "detailed_address": {
      "street_address_1": "101 Market St",
      "street_address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94105",
      "country": "US",
    },
    "notes": "Ring the bell, meow loudly.",
    "location" : {
        "lat" : 37.793274,
        "lng" : -122.395934
    },
  },
  "courier": {
    "name": "Robo Courier",
    "rating": "5.0",
    "vehicle_type": "bicycle",
    "phone_number": "+14151234567"
    "location" : {
        "lat" : 37.42291810,
        "lng" : -122.08542120
    },
    "img_href": "https://images.postmates.com/06c9a53c-f89f-4eac-8861-60e34039d9ea/121.jpg"
  },
  "related_deliveries": [{
    "id": "del_9A3jsld89s",
    "relationship": "original"
  }]
}
Name Description
status
  • pending - We've accepted the delivery and will be assigning it to a courier.
  • pickup - Courier is assigned and is en route to pick up the items.
  • pickup_complete - Courier has picked up the items.
  • dropoff - Courier is moving towards the dropoff.
  • canceled - Items won't be delivered. Deliveries are either canceled by the customer or by our customer service team.
  • delivered - Items were delivered successfully.
  • returned - The delivery was canceled and a new job created to return items to sender. (See related_deliveries in delivery object.)
complete false if the delivery is ongoing, and you can expect additional updates.
pickup_eta Estimated time the courier will arrive at the pickup location.
dropoff_eta Estimated time the courier will arrive at the dropoff location.
dropoff_deadline Based on the delivery window from the delivery quote. If the dropoff_eta goes beyond this dropoff_deadline, our customer service team will be notified. We may extend this value to indicate a known problem.
fee Amount in cents that will be charged if this delivery is created (see "Other Standards » Currency").
currency Currency the "amount" values are in. (see "Other Standards » Currency").
quote_id ID for the Delivery Quote if one was provided when creating this Delivery.
manifest
  • reference - Developer provided identifier for the courier to reference when picking up the package.
  • returned - A free form body describing the package.
dropoff_identifier This field identifies who received delivery at dropoff location.
courier

The courier object is only present when a delivery is in progress.

  • name - Courier's first name.
  • rating - Courier's rating on a scale of 1.0 to 5.0.
  • vehicle_type - The type of vehicle the courier is using. Currently support bicycle, car, van, truck, scooter, motorcycle, and walker.
  • phone_number - The courier's phone number.
  • location - A latitude and longitude indicating courier's location.
  • img_href - A URL to courier's profile image.
related_deliveries

A collection describing other jobs that share an association.

  • id - Unique identifier.
  • relationship - Indicating the nature of the job identified in related_deliveries. "original" for the forward leg of the trip, and "returned" for the return leg of the trip.

List Deliveries

List all deliveries for a customer.

Endpoint

GET /v1/customers/:customer_id/deliveries

Query Parameters

Name Description
filter=ongoing This filter limits the results to only deliveries that are currently being delivered.

Response

{
  "url": "/v1/customers/:customer_id/deliveries",
  "total_count": 18,
  "object": "list",
  "data": [
    // An array of Delivery objects
  ],
  "next_href": "https://api.postmates.com/v1/..."
}

Get a Delivery

Retrieve updated details about a delivery.

Endpoint

GET /v1/customers/:customer_id/deliveries/:delivery_id

Response

See "Create a Delivery" response above.

Cancel a Delivery

Cancel an ongoing delivery. A delivery can only be canceled prior to a courier completing pickup. Delivery fees still apply.

Endpoint

POST /v1/customers/:customer_id/deliveries/:delivery_id/cancel

Response

See "Create a Delivery" response above.

Return a Delivery

This endpoint was deprecated on November 28, 2016.

If a customer is not available at dropoff, we'll either create a return delivery or leave items at the door, depending on your preference.

Endpoint

POST /v1/customers/:customer_id/deliveries/:delivery_id/return

Response

Returns a Delivery object (the new return delivery). See "Create a Delivery" response above.

Add a Tip to a Delivery

After an order has completed, you can add a tip for the courier for up to 7 days.

Endpoint

POST /v1/customers/:customer_id/deliveries/:delivery_id

Query Parameters

Name Description
tip_by_customer Amount in cents that will be paid to the courier as a tip.

Response

Returns a Delivery object. See "Create a Delivery" response above.