Skip to content
First DeliveryFirst DeliveryFirst Delivery API

Create Merchant

POST {{BASE_HABITAT_URL}}/api/v3/merchants

Required scope: merchants:write

Creates a merchant. Every order must have a merchant associated with it.

The id field in a successful response should be saved on your end - this needs to be sent as the merchant_id field when getting quotes and sending orders.

> 🛑 In sandbox and production, make sure to use valid U.S phone numbers. Some DSPs will reject on the basis of a phone number being ‘fake’ (e.g 123456789) or outside the country!

The timezone of the merchant is determined by it’s parent Territory

Request body

Section titled “Request body”
Field Required Description
name Yes Merchant name
address Yes Merchant address
email Yes Merchant email. If you don’t have this or partner directly, you can stub it out with an email on your domain with an incrementing number: e.g merchant+1@firstdelivery.com
phone Yes Merchant phone number
territory_id Yes This is the territory you want to create the merchant within. This is required for timezones among many other feature sets.
cohort_id No (see description) Cohorts are clusters of merchants under territories. For most cases, this is an optional field. If you have more than one cohort for the specified territory, this is a required field. Cohorts / habitats are the same thing.
options No Object with fields:
options.prep_time No Default ‘lead time’ for an ASAP order, when no pickup_time or dropoff_time is passed

Request body

Section titled “Request body”
{
    "name": "{{$randomCompanyName}}",
    "address": "2211 E Hagert ST, Philadelphia, PA",
    "email": "{{$randomEmail}}",
    "phone": "{{$randomPhoneNumber}}",
    "cohort_id": "57b14a67-eb8f-4d65-b063-89a2f704de9d"
}

Examples

Section titled “Examples”
Terminal window
curl --request POST '${BASE_HABITAT_URL}/api/v3/merchants' \
  --data '{
    "name": "{{$randomCompanyName}}",
    "address": "2211 E Hagert ST, Philadelphia, PA",
    "email": "{{$randomEmail}}",
    "phone": "{{$randomPhoneNumber}}",
    "cohort_id": "57b14a67-eb8f-4d65-b063-89a2f704de9d"
}'

Saved responses

Section titled “Saved responses”
{
    "type": "success",
    "data": {
        "id": "9f997881-6794-11ee-9fd4-d1b51b798aba",
        "created_at": "2023-10-10T17:44:12.823Z",
        "name": "Gutkowski, Langworth and Schiller",
        "location": {
            "address": "2211 E Hagert St, Philadelphia, PA 19125, USA",
            "coordinates": {
                "type": "Point",
                "coordinates": [
                    -75.1251352,
                    39.9808023
                ]
            }
        },
        "phone": "2434433247",
        "email": "terrence46@gmail.com",
        "habitat": "627e5f1d-4e66-4533-9aac-14fbdf99b231",
        "territory": "db93f018-36e2-416b-8196-5d3a36033440",
        "timezone": "America/New_York",
        "operator_id": 1,
        "archived": null,
        "options": {
            "prep_time": 20,
            "pickup_instructions": "In the food court",
            "auto_accept": false,
            "priority": false
        },
        "rates": {
            "daas_rate": null,
            "oozo_rate": null,
            "catering_rate": null,
            "scheduled_rate": 15,
            "diner_delivery_fee": null,
            "runner_commission": null
        },
        "billing": {
            "enabled": true,
            "stripe_id": null,
            "invoice_email": "terrence46@gmail.com",
            "invoice_default_type": null
        }
    }
}