Skip to content
First DeliveryFirst DeliveryFirst Delivery API

Get Provider Quotes

POST {{BASE_HABITAT_URL}}/api/v3/quotes

Required scope: quotes:create

Why do I need quotes?

Section titled “Why do I need quotes?”

For basic use cases, you don’t. Getting provider quotes is always an optional step before placing an order. It is mostly useful if your territories and merchants are configured to use Strategies - think of the response as a ‘snapshot’ of what the First algorithm would do if you immediately placed the order. Breaking it down, the Quote response tells you:

  • Which providers are able to fulfill the delivery - including pricing and pickup/dropoff estimates
  • What provider is preferred - Based on your configured Strategies
  • How the preferred provider was determined - the strategy object shows which strategy was used to determine which provider is preferred

When are quotes useful?

Section titled “When are quotes useful?”

The most common use cases for quotes are to give your end-customer:

  • the choice to pick between multiple delivery providers on checkout
  • provide an estimated pickup/delivery time for the preferred provider

Why am I not getting any quotes back?

Section titled “Why am I not getting any quotes back?”
  • Especially in sandbox - make sure the dropoff address is close to the Merchant’s address (at least the same city!)
  • If you are using Strategies, the more constraints you have, the smaller the list of available quotes will be.

Request Body

Section titled “Request Body”
Field Optional? (default) Description
merchant_id ID from create Merchant response
dropoff Address and instructions (see examples for full_address and structured address payloads)
dropoff_time Yes (ASAP) Target dropoff time. If excluded, DSP quote times will reflect ASAP pickup and delivery.
pickup_time Yes (ASAP) Target pickup time. If excluded, DSP quote times will reflect ASAP pickup and delivery.

Response Body

Section titled “Response Body”

The quote response contains the following top-level keys:

  • quotes - successful DSP quotes, with banned DSPs filtered and sorted by your strategy’s prefer ranking.
  • all_quotes - all successful DSP quotes, including banned DSPs
  • strategy - prefer rankings and bans for the strategy used for the quote request
Field Description
id Quote ID, pass this to POST /v3/orders to override strategy
provider Name of the DSP the quote is from
price Price, in cents, the DSP will charge for the delivery
pickup_estimate dropoff_estimate ISODate estimates for pickup and dropoff provided by the DSP
pickup_mins_from_now delivery_mins_from_now Utility for returning the above estimate values in minutes
preferred Preferred DSP according to your Strategy settings
distance Distance from pickup to dropoff metadata. Currently only unit supported is miles, and distance is always crow-flies/great-circle
zone_fees The corresponding zone and pricing attributes, based on delivery distance. Zone Fees are currently only configurable via UI

Request body

Section titled “Request body”
{
    "merchant_id": "{{$merchantId}}",
    "dropoff_by": "2023-03-22T15:44:13.389Z",
    "dropoff": {
        "full_address": "2166 E Norris St., Philadelphia PA, 19125"
    }
}

Examples

Section titled “Examples”
Terminal window
curl --request POST '${BASE_HABITAT_URL}/api/v3/quotes' \
  --data '{
    "merchant_id": "{{$merchantId}}",
    "dropoff_by": "2023-03-22T15:44:13.389Z",
    "dropoff": {
        "full_address": "2166 E Norris St., Philadelphia PA, 19125"
    }
}'

Saved responses

Section titled “Saved responses”
{
    "type": "success",
    "data": {
        "quotes": [
            {
                "id": "8f216bcf-bcf4-4a1f-80bf-f685cf35b5cd",
                "provider": "relay",
                "price": 550,
                "pickup_estimate": "2023-05-17T19:27:24.520Z",
                "dropoff_estimate": "2023-05-17T19:30:24.520Z",
                "delivery_mins_from_now": 17,
                "pickup_mins_from_now": 14,
                "preferred": true,
                "distance": {
                    "type": "crow_flies",
                    "unit": "miles",
                    "value": 0
                },
                "zone_fees": {
                    "id": "1bacea79-9468-47f2-b770-da16c6cc154b",
                    "billable_merchant_fee": 500
                }
            }
        ],
        "all_quotes": [
            {
                "id": "af141609-c665-4674-8c7d-c9fe54fd3936",
                "provider": "doordash",
                "price": 700,
                "pickup_estimate": "2023-05-17T19:27:24.000Z",
                "dropoff_estimate": "2023-05-17T20:13:32.000Z",
                "delivery_mins_from_now": 61,
                "pickup_mins_from_now": 14,
                "preferred": true,
                "distance": {
                    "type": "crow_flies",
                    "unit": "miles",
                    "value": 0
                },
                "zone_fees": {
                    "id": "1bacea79-9468-47f2-b770-da16c6cc154b",
                    "billable_merchant_fee": 500
                }
            },
            {
                "id": "f4fffb32-08ca-40f2-81fb-bdbf93595ee1",
                "provider": "uber",
                "price": 600,
                "pickup_estimate": "2023-05-17T19:12:25.173Z",
                "dropoff_estimate": "2023-05-17T19:44:28.000Z",
                "delivery_mins_from_now": 32,
                "pickup_mins_from_now": 0,
                "preferred": false,
                "distance": {
                    "type": "crow_flies",
                    "unit": "miles",
                    "value": 0
                },
                "zone_fees": {
                    "id": "1bacea79-9468-47f2-b770-da16c6cc154b",
                    "billable_merchant_fee": 500
                }
            },
            {
                "id": "58377c88-011e-40ca-9ec9-1e1be86ffd2b",
                "provider": "ally",
                "price": 819,
                "pickup_estimate": "2023-05-17T19:42:24.000Z",
                "dropoff_estimate": "2023-05-17T19:57:24.000Z",
                "delivery_mins_from_now": 44,
                "pickup_mins_from_now": 29,
                "preferred": false,
                "distance": {
                    "type": "crow_flies",
                    "unit": "miles",
                    "value": 0
                },
                "zone_fees": {
                    "id": "1bacea79-9468-47f2-b770-da16c6cc154b",
                    "billable_merchant_fee": 500
                }
            },
            {
                "id": "8f216bcf-bcf4-4a1f-80bf-f685cf35b5cd",
                "provider": "relay",
                "price": 550,
                "pickup_estimate": "2023-05-17T19:27:24.520Z",
                "dropoff_estimate": "2023-05-17T19:30:24.520Z",
                "delivery_mins_from_now": 17,
                "pickup_mins_from_now": 14,
                "preferred": false,
                "distance": {
                    "type": "crow_flies",
                    "unit": "miles",
                    "value": 0
                },
                "zone_fees": {
                    "id": "1bacea79-9468-47f2-b770-da16c6cc154b",
                    "billable_merchant_fee": 500
                }
            }
        ],
        "strategy": {
            "id": "af55ad1e-4d9b-4721-a38f-7c5895ef0595",
            "operator_id": 1,
            "default": true,
            "tie_breaker": "cheapest",
            "name": "Default (Cheapest)",
            "providers": [
                {
                    "name": "relay",
                    "type": "prefer",
                    "index": 0
                },
                {
                    "name": "doordash",
                    "type": "ban",
                    "index": 0
                },
                {
                    "name": "uber",
                    "type": "ban",
                    "index": 1
                },
                {
                    "name": "ally",
                    "type": "ban",
                    "index": 2
                }
            ]
        }
    }
}