Delivery Window

Fetch the list of available delivery time slots for a customer's location, so you can pass a valid delivery_window_id when placing a delivery order.

Overview

The checkout payload requires a delivery_window_id for any non-pickup order. Delivery windows are provider- and zone-specific — each provider defines time slots, and each slot is attached to one or more delivery zones (polygons on the map). A window is only valid for a customer if their delivery coordinates fall inside a zone that the window is attached to.

Use this endpoint to resolve the customer's lat/lng (and the active city_id) into the list of windows you can actually book.

Endpoint: Get Supported Delivery Windows

When to Call

Customer picks (or already has) a delivery location

You need the location's lat, lng, and the city_id it belongs to.
Coordinates come from the customer location object (see Customer Location).

Call Get Supported Delivery Windows

Pass lat, lng, and city_id as query params.
The response lists every delivery window that covers that point.

Customer picks a window

Show the returned from_time → to_time slots in your UI.
Capture the chosen window's id.

Use it in the checkout payload

Send the chosen id as delivery_window_id when calling Place Order.

Pickup orders skip this step

If is_pickup = true, delivery_window_id is not required and this endpoint does not need to be called.

Request

Headers

Header	Required	Description
`Authorization`	yes	`Bearer <PUBLIC_API_KEY>`. The key must hold the `logistics.read` permission.
`app-id`	yes	Provider app ID — must match the API key's app context.

Query Parameters

Param	Type	Required	Description
`lat`	string	yes	Latitude of the customer's delivery point (decimal degrees, e.g. `"24.7136"`).
`lng`	string	yes	Longitude of the customer's delivery point (e.g. `"46.6753"`).
`city_id`	integer	yes	City ID the location belongs to. Must be the same `city-id` you use when fetching plans and placing the order.

Critical

city_id must be consistent across plans → windows → checkout. A mismatch returns an empty list.

lat / lng must fall inside one of the provider's active delivery zones for that city — otherwise the response is [] and the customer cannot place a delivery order to that point.

Response

200 OK — array of supported windows. Each entry is a window the customer can pick.

[
  {
    "id": 12,
    "from_time": "12:00:00",
    "to_time": "14:00:00",
    "zone": {
      "id": 7,
      "name": "Olaya - North"
    }
  },
  {
    "id": 18,
    "from_time": "18:00:00",
    "to_time": "20:00:00",
    "zone": {
      "id": 7,
      "name": "Olaya - North"
    }
  }
]

Response Fields

Field	Type	Description
`id`	integer	Delivery window ID — this is the value to send as `delivery_window_id` in the order payload.
`from_time`	string (`HH:MM:SS`)	Window start time (provider's local timezone, `Asia/Riyadh`).
`to_time`	string (`HH:MM:SS`)	Window end time.
`zone.id`	integer	The delivery zone that matched the customer's coordinates.
`zone.name`	string	Human-readable zone name (useful for support/debugging — not usually shown to the customer).

Sorted by start time

Results are ordered by from_time ascending, so you can render them as-is in a "pick a slot" UI.

Wiring it into Place Order

Take the chosen id and drop it directly into the delivery order payload:

{
  "delivery_window_id": 12,
  "location": {
    "id": 9989,
    "is_corporate_location": false
  },
  "cart_items": [ ... ],
  "is_subscription": true
}

See Place Order for the full payload structure.

Common Issues

Empty list returned

Problem: The endpoint returns [].

Causes:

The customer's lat/lng is outside every active delivery zone for this provider in this city.

city_id does not match the zones (e.g. coordinates are in Riyadh but city_id points to Jeddah).

The provider has no zones configured for that city, or all its zones are inactive.

Solution: Confirm the location is inside the provider's coverage area, and that city_id matches the city of the coordinates.

`delivery_window_id is required for delivery plans`

Problem: Place Order rejects the payload.

Solution: This endpoint must be called and a valid id must be passed as delivery_window_id. Pickup orders should instead send is_pickup: true and pickup_branch_id.

Window from a different provider

Problem: Place Order errors with an invalid delivery window.

Solution: Windows are scoped to the provider in the app-id header. Re-fetch using the same app-id you will use for Place Order.

Wrong `app-id` Header

Problem: 403 / "api key is not valid for this app".

Solution: Use the provider's app ID (the one tied to your public API key), not your sales channel app ID.

Quick Reference


Method	`GET`
Path	`/public-api/v1/logistics/supported-windows/`
Auth	Public API key (Bearer)
Required permission	`logistics.read`
Required headers	`Authorization`, `app-id`
Required query params	`lat`, `lng`, `city_id`
Returns	`[{ id, from_time, to_time, zone: { id, name } }]`

Overview#

When to Call#

Request#

Headers#

Query Parameters#

Response#

Response Fields#

Wiring it into Place Order#

Common Issues#

Empty list returned#

delivery_window_id is required for delivery plans#

Window from a different provider#

Wrong app-id Header#

Quick Reference#

Overview

When to Call

Request

Headers

Query Parameters

Response

Response Fields

Wiring it into Place Order

Common Issues

Empty list returned

`delivery_window_id is required for delivery plans`

Window from a different provider

Wrong `app-id` Header

Quick Reference