Fetch Delivery Slots

This endpoint is part of the advanced Home Delivery integration, where consumers can choose between different available delivery days. Only implement this if you have agreed on this setup with your Implementation Manager.

For the standard integration, use Validate Postal Code instead — which simply confirms whether we deliver to the postal code.

The Availability API accepts both GET and POST requests and returns available delivery windows for home delivery.

Overview

When using the advanced delivery slot flow, this endpoint allows you to:

1. Validate if a postal code is serviceable
2. Get available delivery slots for an address
3. Filter options by brand, dates, and other preferences

Current setup looks something like this:

With Instabee API we will be able to clean up the above mess

And in the future this will enable us to get to this beautiful stage.

Key Concepts

Availability Token

Availability API endpoints return an availability token that you must save and use when creating a parcel. This token contains essential information about the selected delivery option and is valid for 14 days. Optional integration paths exist, talk to your Implementation Manager for more information.

Postal Code Validation

Validating a postal code is the first step in determining if Instabee can provide delivery services to a particular area. Not all postal codes are serviceable - this can depend on the delivery type (home vs locker) and brand.

Delivery Windows

For home delivery services, the API returns time slots (delivery windows)if requested when a delivery can be made. These slots typically include:

• Date (YYYY-MM-DD format)
• Start time (HH:MM format)
• End time (HH:MM format)

Endpoints

Unified Endpoint Design

The new Availability API consolidates all delivery options into a single, unified endpoint that supports both GET and POST methods:

• GET Method: For lightweight requests using query parameters (minimal availability checks)
• POST Method: For full-featured requests with request body (complex scenarios with cart, dispatch, options)

Get Delivery Options

Unified Endpoint for All Delivery Types

Endpoint

Production

GET/POST api.integration.instabee.com/availability/countries/{countryCode}/postal-codes/{postalCode}/delivery-options

Sandbox

GET/POST sandbox-api.integration.instabee.com/availability/countries/{countryCode}/postal-codes/{postalCode}/delivery-options

Same path as production; use sandbox credentials.

Path Parameters:

• {countryCode} - Required. Country code (DK, FI,NO, SE)
• {postalCode} - Required. Postal code to check availability

Query Parameters (Required for both GET and POST):

• brand - Required. Brand identifier (e.g., budbee, porterbuddy)
• product - Required. Product type: HOME_DELIVERY

You can call this endpoint with different levels of information depending on your needs.

Home Delivery

Get Home Delivery Options

Endpoint

Production

GET/POST api.integration.instabee.com/availability/countries/{countryCode}/postal-codes/{postalCode}/delivery-options

Sandbox

GET/POST sandbox-api.integration.instabee.com/availability/countries/{countryCode}/postal-codes/{postalCode}/delivery-options

Same path as production; use sandbox credentials.

Required Query/Body Parameters:

• brand - Brand identifier
• product - Set to HOME_DELIVERY

1POST /availability/countries/SE/postal-codes/11353/delivery-options
2Content-Type: application/json
1POST /availability/countries/SE/postal-codes/11353/delivery-options
2Content-Type: application/json

1{
2  "brand": "instabox",
3  "product": "HOME_DELIVERY",
4  "recipient": {
5    "street": "Hälsingegatan 40",
6    "city": "Stockholm",
7    "email": "test@instabee.com"
8  },
9  "deliverySlotCount": 7
10}
1{
2  "brand": "instabox",
3  "product": "HOME_DELIVERY",
4  "recipient": {
5    "street": "Hälsingegatan 40",
6    "city": "Stockholm",
7    "email": "test@instabee.com"
8  },
9  "deliverySlotCount": 7
10}

Response Code: 201 (Created)

1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5        {
6            "sortCode": "INh0",
7            "type": "HOMEDELIVERY",
8            "brand": "Instabox",
9            "deliveryOption": "Monday May 13, 16:00-22:30",
10            "deliveryOptionWithEta": "Monday May 13, 16:00-22:30",
11            "eta": {
12                "certainty": "INTERVAL",
13                "etaInterval": {
14                    "from": "2025-05-13T16:00:00.000Z",
15                    "to": "2025-05-13T22:30:00.000Z"
16                }
17            },
18            "localEta": {
19                "date": "2025-05-13",
20                "dayText": "Monday"
21            },
22            "packBeforeDatetime": "2025-05-12T19:30:00.000Z",
23            "consumerCutoffDatetime": "2025-05-11T12:00:00.000Z",
24            "consolidation": false
25        }
26    ],
27    "preselection": "RECOMMENDED",
28    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
29    "showAsOptionInCheckout": true
30}
1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5        {
6            "sortCode": "INh0",
7            "type": "HOMEDELIVERY",
8            "brand": "Instabox",
9            "deliveryOption": "Monday May 13, 16:00-22:30",
10            "deliveryOptionWithEta": "Monday May 13, 16:00-22:30",
11            "eta": {
12                "certainty": "INTERVAL",
13                "etaInterval": {
14                    "from": "2025-05-13T16:00:00.000Z",
15                    "to": "2025-05-13T22:30:00.000Z"
16                }
17            },
18            "localEta": {
19                "date": "2025-05-13",
20                "dayText": "Monday"
21            },
22            "packBeforeDatetime": "2025-05-12T19:30:00.000Z",
23            "consumerCutoffDatetime": "2025-05-11T12:00:00.000Z",
24            "consolidation": false
25        }
26    ],
27    "preselection": "RECOMMENDED",
28    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
29    "showAsOptionInCheckout": true
30}

Response Details:

• product: Use HOME_DELIVERY for home delivery requests
• type: Delivery type in UPPERCASE format ("HOMEDELIVERY")

Request Parameters

The Availability API accepts various parameters to customize the delivery options returned. Here's a comprehensive reference of all available parameters.

Endpoint Overview

Path Parameters

Query Parameters (GET Method)

For GET requests, these parameters are passed as query strings:

Request Body (POST Method)

The Availability API accepts a JSON request body with detailed information about the recipient, cart, and delivery preferences.

---

recipient

---

dispatch

Note: Only one of readyToShip, readyToPack, outOfStock can be provided

---

options

options.responseFields

---

cart

cart.parcel

cart.parcel.products

cart.parcel.products.details

cart.parcel.products.details.price

cart.parcel.products.details.temperature

cart.parcel.products.packages

cart.parcel.products.packages.barcodes

Response Parameters

The Availability API returns comprehensive information about available delivery options, including lockers and home delivery slots.

Common Response Fields

Home Delivery Response

For home delivery requests, the response includes delivery time slots and sender information.

Additional Fields for Home Delivery

deliveryOptions

Error Handling

The API may return the following errors: