Skip to content
First DeliveryFirst DeliveryFirst Delivery API

Create Territory

POST {{BASE_HABITAT_URL}}/api/v3/territories

Required scope: territories:write

A territory is a geographic zone under which merchants and runners are grouped. This gives you the ability to

  • configure DSP routing strategies

  • apply settings to groups of runners in a given market (e.g per-order commission, block restrictions)

  • apply settings to groups of restaurants in a given market (e.g alert messages)

I manage my own fleet…

Section titled “I manage my own fleet…”

If you don’t have your own drivers, you can skip this section!

If you have a delivery fleet, there are multiple defaults you can set on a territory, relating to how you charge merchants, how you schedule & pay runners, and how orders are dispatched. These will typically be disregarded if you use Strategies to route orders to our DSP network.

Field Type Required Description
merchant_commission.base number No Per delivery charge for the merchant.
runner_commission.base number Yes Per delivery payment for the runner.
runner_commission.base_outside_zone number No The additional commission amount for the runner when delivering outside the territory zone.
runner_scheduling.schedule_publish_days_out number Yes The number of days in advance that shifts will be published to runners.
runner_scheduling.schedule_max_callout_percent number or null No Fleet-only, % at which the forecasting model will forecast called-out shifts
runner_scheduling.hide_open_shifts boolean Yes Whether to hide open shifts from runners.
self_fulfillment.use_engine boolean Yes Whether to suggest order assigns with the First dispatch engine.
self_fulfillment.auto_route boolean Yes Whether to automatically optimize order of pickups and dropoffs
self_fulfillment.auto_assign boolean Yes Whether to automatically assign orders based on First engine suggestion
self_fulfillment.auto_assign_filter_mins number or null No Minutes before an order’s pickup estimate until engine suggests
self_fulfillment.require_signature boolean Yes Whether to require a signature for self-fulfilled orders.

I use external fleets…

Section titled “I use external fleets…”

If you use our DSP network as your fleet, configuration is a lot simpler! The only default setting available is whether or not to auto-dispatch to a DSP based on your Strategy configuration when you Create an Order.

Depending on your spread of merchants, we recommend setting up either:

  • one territory per city (if your merchants are clustered in cities)

  • one territory per timezone (if merchants are spread randomly)

For the DSP-only use case, the zone geojson - though required - is arbitrary and has no effect on any business logic (fleets, coverage, etc). We recommend using geojson.io to generate this value.

Field Type (default) Required Description
auto_dispatch Boolean (false) No Set to true so that by default, an order request is automatically routed to the DSP based on Strategy

Request body

Section titled “Request body”
{
    "name": "mikes testaaaa",
    "shortcode": "PAHL",
    "runner_commission": 5,
    "zone": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -84.39102792034079,
                    33.95189377729187
                ],
                [
                    -84.41501821353695,
                    33.95091381561112
                ],
                [
                    -84.4387758271438,
                    33.947983435458944
                ],
                [
                    -84.46207038619055,
                    33.943131057341354
                ],
                [
                    -84.48467610023073,
                    33.93640373589924
                ],
                [
                    -84.50637399416374,
                    33.92786669412983
                ],
                [
                    -84.52695406627284,
                    33.91760267829743
                ],
                [
                    -84.54621735077312,
                    33.905711140417196
                ],
                [
                    -84.5639778634478,
                    33.89230725700097
                ],
                [
                    -84.58006441050702,
                    33.87752079444011
                ],
                [
                    -84.59432224259055,
                    33.861494832950754
                ],
                [
                    -84.60661453782244,
                    33.844384362401016
                ],
                [
                    -84.6168236999679,
                    33.82635476456462
                ],
                [
                    -84.62485246000432,
                    33.80758019739014
                ],
                [
                    -84.63062477175282,
                    33.788241897731346
                ],
                [
                    -84.63408649458894,
                    33.76852641964817
                ],
                [
                    -84.63520585862256,
                    33.74862382585801
                ],
                [
                    -84.63397371007004,
                    33.72872585019602
                ],
                [
                    -84.6304035368112,
                    33.7090240490338
                ],
                [
                    -84.6245312762983,
                    33.68970795951668
                ],
                [
                    -84.61641491004595,
                    33.67096328221778
                ],
                [
                    -84.60613385086107,
                    33.652970105382664
                ],
                [
                    -84.59378813075895,
                    33.63590118736425
                ],
                [
                    -84.57949739914682,
                    33.61992031313222
                ],
                [
                    -84.56339974233799,
                    33.60518073990102
                ],
                [
                    -84.54565033678375,
                    33.5918237459647
                ],
                [
                    -84.52641994958314,
                    33.57997729576967
                ],
                [
                    -84.505893300855,
                    33.569754833108924
                ],
                [
                    -84.48426730343844,
                    33.56125421309614
                ],
                [
                    -84.46174919613713,
                    33.554556782284926
                ],
                [
                    -84.43855458734413,
                    33.54972661494938
                ],
                [
                    -84.41490542638887,
                    33.546809912146
                ],
                [
                    -84.39102792034079,
                    33.545834568743665
                ],
                [
                    -84.36715041429268,
                    33.546809912146
                ],
                [
                    -84.34350125333744,
                    33.54972661494938
                ],
                [
                    -84.32030664454443,
                    33.554556782284926
                ],
                [
                    -84.29778853724312,
                    33.56125421309614
                ],
                [
                    -84.27616253982656,
                    33.569754833108924
                ],
                [
                    -84.25563589109842,
                    33.57997729576967
                ],
                [
                    -84.23640550389781,
                    33.5918237459647
                ],
                [
                    -84.21865609834356,
                    33.60518073990102
                ],
                [
                    -84.20255844153475,
                    33.61992031313222
                ],
                [
                    -84.18826770992261,
                    33.63590118736425
                ],
                [
                    -84.17592198982048,
                    33.652970105382664
                ],
                [
                    -84.1656409306356,
                    33.67096328221778
                ],
                [
                    -84.15752456438325,
                    33.68970795951668
                ],
                [
                    -84.15165230387036,
                    33.7090240490338
                ],
                [
                    -84.14808213061151,
                    33.72872585019602
                ],
                [
                    -84.14684998205901,
                    33.74862382585801
                ],
                [
                    -84.14796934609262,
                    33.76852641964817
                ],
                [
                    -84.15143106892874,
                    33.788241897731346
                ],
                [
                    -84.15720338067723,
                    33.80758019739014
                ],
                [
                    -84.16523214071367,
                    33.82635476456462
                ],
                [
                    -84.17544130285913,
                    33.844384362401016
                ],
                [
                    -84.18773359809101,
                    33.861494832950754
                ],
                [
                    -84.20199143017454,
                    33.87752079444011
                ],
                [
                    -84.21807797723376,
                    33.89230725700097
                ],
                [
                    -84.23583848990843,
                    33.905711140417196
                ],
                [
                    -84.25510177440873,
                    33.91760267829743
                ],
                [
                    -84.27568184651784,
                    33.92786669412983
                ],
                [
                    -84.29737974045082,
                    33.93640373589924
                ],
                [
                    -84.31998545449102,
                    33.943131057341354
                ],
                [
                    -84.34328001353774,
                    33.947983435458944
                ],
                [
                    -84.36703762714461,
                    33.95091381561112
                ],
                [
                    -84.39102792034079,
                    33.95189377729187
                ]
            ]
        ]
    },
    "center": {
        "type": "Point",
        "coordinates": [
            -81.59097400000002,
            41.4449243
        ]
    }
}

Examples

Section titled “Examples”
Terminal window
curl --request POST '${BASE_HABITAT_URL}/api/v3/territories' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "mikes testaaaa",
    "shortcode": "PAHL",
    "runner_commission": 5,
    "zone": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -84.39102792034079,
                    33.95189377729187
                ],
                [
                    -84.41501821353695,
                    33.95091381561112
                ],
                [
                    -84.4387758271438,
                    33.947983435458944
                ],
                [
                    -84.46207038619055,
                    33.943131057341354
                ],
                [
                    -84.48467610023073,
                    33.93640373589924
                ],
                [
                    -84.50637399416374,
                    33.92786669412983
                ],
                [
                    -84.52695406627284,
                    33.91760267829743
                ],
                [
                    -84.54621735077312,
                    33.905711140417196
                ],
                [
                    -84.5639778634478,
                    33.89230725700097
                ],
                [
                    -84.58006441050702,
                    33.87752079444011
                ],
                [
                    -84.59432224259055,
                    33.861494832950754
                ],
                [
                    -84.60661453782244,
                    33.844384362401016
                ],
                [
                    -84.6168236999679,
                    33.82635476456462
                ],
                [
                    -84.62485246000432,
                    33.80758019739014
                ],
                [
                    -84.63062477175282,
                    33.788241897731346
                ],
                [
                    -84.63408649458894,
                    33.76852641964817
                ],
                [
                    -84.63520585862256,
                    33.74862382585801
                ],
                [
                    -84.63397371007004,
                    33.72872585019602
                ],
                [
                    -84.6304035368112,
                    33.7090240490338
                ],
                [
                    -84.6245312762983,
                    33.68970795951668
                ],
                [
                    -84.61641491004595,
                    33.67096328221778
                ],
                [
                    -84.60613385086107,
                    33.652970105382664
                ],
                [
                    -84.59378813075895,
                    33.63590118736425
                ],
                [
                    -84.57949739914682,
                    33.61992031313222
                ],
                [
                    -84.56339974233799,
                    33.60518073990102
                ],
                [
                    -84.54565033678375,
                    33.5918237459647
                ],
                [
                    -84.52641994958314,
                    33.57997729576967
                ],
                [
                    -84.505893300855,
                    33.569754833108924
                ],
                [
                    -84.48426730343844,
                    33.56125421309614
                ],
                [
                    -84.46174919613713,
                    33.554556782284926
                ],
                [
                    -84.43855458734413,
                    33.54972661494938
                ],
                [
                    -84.41490542638887,
                    33.546809912146
                ],
                [
                    -84.39102792034079,
                    33.545834568743665
                ],
                [
                    -84.36715041429268,
                    33.546809912146
                ],
                [
                    -84.34350125333744,
                    33.54972661494938
                ],
                [
                    -84.32030664454443,
                    33.554556782284926
                ],
                [
                    -84.29778853724312,
                    33.56125421309614
                ],
                [
                    -84.27616253982656,
                    33.569754833108924
                ],
                [
                    -84.25563589109842,
                    33.57997729576967
                ],
                [
                    -84.23640550389781,
                    33.5918237459647
                ],
                [
                    -84.21865609834356,
                    33.60518073990102
                ],
                [
                    -84.20255844153475,
                    33.61992031313222
                ],
                [
                    -84.18826770992261,
                    33.63590118736425
                ],
                [
                    -84.17592198982048,
                    33.652970105382664
                ],
                [
                    -84.1656409306356,
                    33.67096328221778
                ],
                [
                    -84.15752456438325,
                    33.68970795951668
                ],
                [
                    -84.15165230387036,
                    33.7090240490338
                ],
                [
                    -84.14808213061151,
                    33.72872585019602
                ],
                [
                    -84.14684998205901,
                    33.74862382585801
                ],
                [
                    -84.14796934609262,
                    33.76852641964817
                ],
                [
                    -84.15143106892874,
                    33.788241897731346
                ],
                [
                    -84.15720338067723,
                    33.80758019739014
                ],
                [
                    -84.16523214071367,
                    33.82635476456462
                ],
                [
                    -84.17544130285913,
                    33.844384362401016
                ],
                [
                    -84.18773359809101,
                    33.861494832950754
                ],
                [
                    -84.20199143017454,
                    33.87752079444011
                ],
                [
                    -84.21807797723376,
                    33.89230725700097
                ],
                [
                    -84.23583848990843,
                    33.905711140417196
                ],
                [
                    -84.25510177440873,
                    33.91760267829743
                ],
                [
                    -84.27568184651784,
                    33.92786669412983
                ],
                [
                    -84.29737974045082,
                    33.93640373589924
                ],
                [
                    -84.31998545449102,
                    33.943131057341354
                ],
                [
                    -84.34328001353774,
                    33.947983435458944
                ],
                [
                    -84.36703762714461,
                    33.95091381561112
                ],
                [
                    -84.39102792034079,
                    33.95189377729187
                ]
            ]
        ]
    },
    "center": {
        "type": "Point",
        "coordinates": [
            -81.59097400000002,
            41.4449243
        ]
    }
}'

Saved responses

Section titled “Saved responses”
{
    "type": "success",
    "territory": {
        "cohort_id": "77fcf6aa-e5ae-4d4d-8112-870f50c882ad",
        "id": "8bce8585-3bce-49d5-a0a5-e9f9ef9bb5e4",
        "created_at": "2023-03-31T14:05:35.453Z",
        "name": "Philadelphia",
        "shortcode": "KPHL",
        "timezone": "America/New_York",
        "zone": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -75.23706796225697,
                        40.0243892939653
                    ],
                    [
                        -75.23706796225697,
                        39.88795290758631
                    ],
                    [
                        -75.06120863215956,
                        39.88795290758631
                    ],
                    [
                        -75.06120863215956,
                        40.0243892939653
                    ],
                    [
                        -75.23706796225697,
                        40.0243892939653
                    ]
                ]
            ]
        },
        "center": {
            "type": "Point",
            "coordinates": [
                -81.59097,
                41.444923
            ]
        },
        "operator_id": 9,
        "auto_dispatch": true,
        "options": {
            "merchant_commission": {
                "base": 5.99
            },
            "runner_commission": {
                "base": 5,
                "base_outside_zone": 1.5
            },
            "runner_scheduling": {
                "schedule_publish_days_out": 6,
                "schedule_max_callout_percent": null,
                "hide_open_shifts": false
            },
            "ext_fulfillment": {
                "strategy_id": "bd262173-9040-4eba-a03d-6d8c25c3eca8"
            },
            "self_fulfillment": {
                "use_engine": true,
                "auto_route": false,
                "auto_assign": false,
                "auto_assign_filter_mins": null,
                "require_signature": false
            }
        }
    }
}