Availability API

This availability check must be performed immediately before creating an order. The recipient's address is required for this call — a postal code alone is not sufficient. If the response returns a locker, proceed to create the order. If no locker is returned, do not create an order.

The Availability API supports both GET and POST methods:

• GET Method: Lightweight request using query parameters
• POST Method: Full-featured request with a request body — use this for Locker Capacity Surplus as address is required

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 (BE, DK, FI, NL, NO, SE)
• {postalCode} - Required. Postal code to check availability

Query Parameters (Required for both GET and POST):

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

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

recipient.coordinates

---

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.

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.

Common Response Fields

Locker Delivery Response

deliveryOptions

deliveryOptions.eta

deliveryOptions.eta.etaInterval

deliveryOptions.localEta

deliveryOptions.directions

deliveryOptions.address

deliveryOptions.address.coordinates

deliveryOptions.deliveryPrice

deliveryOptions.distance

deliveryOptions.openHours

Error Handling

The API may return the following errors:

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

Minimal Request (GET Method)

Use Case: Simple availability check with minimal parameters

Example:

1GET /availability/countries/SE/postal-codes/11353/delivery-options?brand=instabox&product=LOCKER_CAPACITY_SURPLUS
1GET /availability/countries/SE/postal-codes/11353/delivery-options?brand=instabox&product=LOCKER_CAPACITY_SURPLUS

Parameters:

• countryCode (path): SE - Required path parameter
• postalCode (path): 11353 - Required path parameter
• brand (query): instabox - Required
• product (query): LOCKER_CAPACITY_SURPLUS - Required

Required Query Parameters:

• address - Recipient street address

Optional Query Parameters:

• city - Recipient city
• email - Recipient email (for geolocation and favorites)
• deliverySlotsByDate - Specific date range
• readyToShip - ISO-8601 datetime
• readyToPack - ISO-8601 datetime

Optimal Request (POST Method)

Use Case: Include recipient information for better geolocation and personalized results

Example:

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": "LOCKER_CAPACITY_SURPLUS",
4  "recipient": {
5    "email": "test@instabee.com",
6    "street": "Hälsingegatan 40",
7    "street2": "Floor 10",
8    "city": "Stockholm"
9  }
10}
1{
2  "brand": "instabox",
3  "product": "LOCKER_CAPACITY_SURPLUS",
4  "recipient": {
5    "email": "test@instabee.com",
6    "street": "Hälsingegatan 40",
7    "street2": "Floor 10",
8    "city": "Stockholm"
9  }
10}

Benefits:

• Email: Better geolocation for returning customers and favorite locker recommendations
• Street/City: Improved distance calculations and sorting
• Full POST body: Access to all advanced features

Maximum Request (POST Method)

Use Case: Full-featured request with cart, dispatch options, and custom response fields

Example:

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": "LOCKER_CAPACITY_SURPLUS",
4  "merchantBrandId": "Merchant1",
5  "sender": {
6    "name": "Merchant A",
7    "email": "test@instabee.com",
8    "phone": "0701234567",
9    "street": "Hälsingegatan 40",
10    "street2": "Floor 10",
11    "city": "Stockholm",
12    "postalCode": "11353",
13    "countryCode": "SE",
14    "coordinates": {
15        "lon": 18.060796,
16        "lat": 59.343971
17    }
18  },
19  "recipient": {
20    "name": "John Doe",
21    "email": "test@instabee.com",
22    "phone": "0701234567",
23    "street": "Hälsingegatan 40",
24    "street2": "Floor 10",
25    "city": "Stockholm",
26    "postalCode": "11353",
27    "countryCode": "SE",
28    "ssn": "19900101-1234",
29    "coordinates": {
30        "lon": 18.060796,
31        "lat": 59.343971
32    }
33  },
34  "dispatch": {
35    "readyToShip": "2025-12-01T01:23:45.678Z",
36    "readyToPack": "2025-11-30T12:00:00.000Z",
37    "packingTime": 120,
38    "collectionPointId": "STOCKHOLM_12345",
39    "outOfStock": false
40  },
41  "options": {
42    "responseFields": {
43      "directions": true,
44      "openHours": true,
45      "distance": true,
46      "lockerAddress": true,
47      "outdoor": true,
48      "price": true,
49      "localEtas": true,
50      "estimatedParcelType": true,
51      "recipient": true,
52      "sender": true
53    },
54    "languageCode": "en"
55  },
56  "cart": {
57    "checkoutId": "XBO12-2923048",
58    "orderNumber": "12345",
59    "totalValueInCents": 12300,
60    "totalWeightInGrams": 30000,
61    "parcel": {
62        "heightMm": 100,
63        "widthMm": 100,
64        "lengthMm": 100,
65        "volumeDm3": 1,
66        "estimatedSize": "SMALL",
67        "weightGram": 2000,
68        "type": "BOX"
69    }
70  }
71}
1{
2  "brand": "instabox",
3  "product": "LOCKER_CAPACITY_SURPLUS",
4  "merchantBrandId": "Merchant1",
5  "sender": {
6    "name": "Merchant A",
7    "email": "test@instabee.com",
8    "phone": "0701234567",
9    "street": "Hälsingegatan 40",
10    "street2": "Floor 10",
11    "city": "Stockholm",
12    "postalCode": "11353",
13    "countryCode": "SE",
14    "coordinates": {
15        "lon": 18.060796,
16        "lat": 59.343971
17    }
18  },
19  "recipient": {
20    "name": "John Doe",
21    "email": "test@instabee.com",
22    "phone": "0701234567",
23    "street": "Hälsingegatan 40",
24    "street2": "Floor 10",
25    "city": "Stockholm",
26    "postalCode": "11353",
27    "countryCode": "SE",
28    "ssn": "19900101-1234",
29    "coordinates": {
30        "lon": 18.060796,
31        "lat": 59.343971
32    }
33  },
34  "dispatch": {
35    "readyToShip": "2025-12-01T01:23:45.678Z",
36    "readyToPack": "2025-11-30T12:00:00.000Z",
37    "packingTime": 120,
38    "collectionPointId": "STOCKHOLM_12345",
39    "outOfStock": false
40  },
41  "options": {
42    "responseFields": {
43      "directions": true,
44      "openHours": true,
45      "distance": true,
46      "lockerAddress": true,
47      "outdoor": true,
48      "price": true,
49      "localEtas": true,
50      "estimatedParcelType": true,
51      "recipient": true,
52      "sender": true
53    },
54    "languageCode": "en"
55  },
56  "cart": {
57    "checkoutId": "XBO12-2923048",
58    "orderNumber": "12345",
59    "totalValueInCents": 12300,
60    "totalWeightInGrams": 30000,
61    "parcel": {
62        "heightMm": 100,
63        "widthMm": 100,
64        "lengthMm": 100,
65        "volumeDm3": 1,
66        "estimatedSize": "SMALL",
67        "weightGram": 2000,
68        "type": "BOX"
69    }
70  }
71}

Response Code: 201 (Created)

Minimum Response (default)

This is to minimize the payload size:

1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5      {
6        "sortCode": "IN123",
7        "type": "LOCKER",
8        "brand": "Instabox",
9        "deliveryOption": "Central Station Stockholm",
10        "deliveryOptionWithEta": "Central Station Stockholm (today ~16:10)",
11        "eta": {
12            "certainty": "EXACT",
13            "etaExact": "2025-06-29T14:10:00.000Z"
14        },
15        "packBeforeDatetime": "2025-06-28T19:30:00.000Z",
16        "consolidation": false
17      }
18    ],
19    "preselection": "RECOMMENDED",
20    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
21    "showAsOptionInCheckout": true
22}
1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5      {
6        "sortCode": "IN123",
7        "type": "LOCKER",
8        "brand": "Instabox",
9        "deliveryOption": "Central Station Stockholm",
10        "deliveryOptionWithEta": "Central Station Stockholm (today ~16:10)",
11        "eta": {
12            "certainty": "EXACT",
13            "etaExact": "2025-06-29T14:10:00.000Z"
14        },
15        "packBeforeDatetime": "2025-06-28T19:30:00.000Z",
16        "consolidation": false
17      }
18    ],
19    "preselection": "RECOMMENDED",
20    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
21    "showAsOptionInCheckout": true
22}

Response Details:

• Response code is 201 (Created)

Maximum Response

With all optional fields included:

1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5        {
6            "labelCode": "IN123",
7            "sortCode": "IN123wOx9dJ",
8            "type": "LOCKER",
9            "brand": "Instabox",
10            "collectionPointId": "CP123",
11            "deliveryOption": "Central Station Stockholm",
12            "deliveryOptionWithEta": "Central Station Stockholm (today ~16:10)",
13             "eta": {
14                "certainty": "EXACT",
15                "etaExact": "2025-06-29T14:10:00.000Z",
16                "etaInterval": {
17                    "from": "2025-07-05T14:10:00.000Z",
18                    "to": "2025-07-06T15:10:00.000Z"
19                }
20            },
21            "localEta": {
22                "date": "2025-06-29",
23                "dayText": "today",
24                "etaTimeExact": "16:10"
25            },
26            "consumerCutoffDatetime": "2025-06-27T12:00:00.000Z",
27            "packBeforeDatetime": "2025-06-28T19:30:00.000Z",
28            "directions": {
29                "short": "Take the exit towards Vasagatan. Your Instabox is located in the Convenience Store at the exit",
30                "long": "Take the exit towards Vasagatan. Your Instabox is located in the Convenience Store at the exit. Go to the man behind the counter with a moustache and answer these three questions: 1. What is your name? 2. What is your quest? 3. What is the air-speed velocity of an unladen swallow?"
31            },
32            "address": {
33                "street": "Tulegatan 14",
34                "postalCode": "11353",
35                "city": "Stockholm",
36                "countryCode": "SE",
37                "country": "Sweden",
38                "coordinates": {
39                    "lat": 59.343971,
40                    "lon": 18.060796
41                }
42            },
43            "deliveryPrice": {
44                "priceInCents": "14900",
45                "currency": "SEK"
46            },
47            "distance": {
48                "unit": "meter",
49                "value": 177,
50                "text": "0.2 km",
51                "type": "EUCLIDEAN"
52            },
53            "openHours": [
54                {
55                    "date": "2025-06-29",
56                    "isOpen": true,
57                    "open": "2025-06-28T22:00:00.000Z",
58                    "close": "2025-06-29T21:59:00.000Z",
59                    "textLocal": "00:00-23:59"
60                }
61            ],
62            "outdoor": false,
63            "consolidation": false
64        }
65    ],
66    "preselection": "RECOMMENDED",
67    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
68    "showAsOptionInCheckout": true,
69    "estimatedParcelType": "SIZE_A",
70    "recipient": {
71        "name": "John Doe",
72        "email": "test@instabee.com",
73        "phone": "0701234567",
74        "street": "Hälsingegatan 40",
75        "street2": "Floor 10",
76        "city": "Stockholm",
77        "postalCode": "11353",
78        "countryCode": "SE",
79        "coordinates": {
80            "lat": 59.343971,
81            "lon": 18.060796
82        }
83    },
84    "sender": {
85        "name": "Merchant A",
86        "email": "merchant@instabee.com",
87        "city": "Stockholm",
88        "countryCode": "SE"
89    }
90}
1{
2    "availabilityToken": "019d8c17-7f32-74bf-8257-bde6184c63db",
3    "checkoutId": "XBO12-2923048",
4    "deliveryOptions": [
5        {
6            "labelCode": "IN123",
7            "sortCode": "IN123wOx9dJ",
8            "type": "LOCKER",
9            "brand": "Instabox",
10            "collectionPointId": "CP123",
11            "deliveryOption": "Central Station Stockholm",
12            "deliveryOptionWithEta": "Central Station Stockholm (today ~16:10)",
13             "eta": {
14                "certainty": "EXACT",
15                "etaExact": "2025-06-29T14:10:00.000Z",
16                "etaInterval": {
17                    "from": "2025-07-05T14:10:00.000Z",
18                    "to": "2025-07-06T15:10:00.000Z"
19                }
20            },
21            "localEta": {
22                "date": "2025-06-29",
23                "dayText": "today",
24                "etaTimeExact": "16:10"
25            },
26            "consumerCutoffDatetime": "2025-06-27T12:00:00.000Z",
27            "packBeforeDatetime": "2025-06-28T19:30:00.000Z",
28            "directions": {
29                "short": "Take the exit towards Vasagatan. Your Instabox is located in the Convenience Store at the exit",
30                "long": "Take the exit towards Vasagatan. Your Instabox is located in the Convenience Store at the exit. Go to the man behind the counter with a moustache and answer these three questions: 1. What is your name? 2. What is your quest? 3. What is the air-speed velocity of an unladen swallow?"
31            },
32            "address": {
33                "street": "Tulegatan 14",
34                "postalCode": "11353",
35                "city": "Stockholm",
36                "countryCode": "SE",
37                "country": "Sweden",
38                "coordinates": {
39                    "lat": 59.343971,
40                    "lon": 18.060796
41                }
42            },
43            "deliveryPrice": {
44                "priceInCents": "14900",
45                "currency": "SEK"
46            },
47            "distance": {
48                "unit": "meter",
49                "value": 177,
50                "text": "0.2 km",
51                "type": "EUCLIDEAN"
52            },
53            "openHours": [
54                {
55                    "date": "2025-06-29",
56                    "isOpen": true,
57                    "open": "2025-06-28T22:00:00.000Z",
58                    "close": "2025-06-29T21:59:00.000Z",
59                    "textLocal": "00:00-23:59"
60                }
61            ],
62            "outdoor": false,
63            "consolidation": false
64        }
65    ],
66    "preselection": "RECOMMENDED",
67    "responseExpiresAt": "2026-04-14T14:04:03.378Z",
68    "showAsOptionInCheckout": true,
69    "estimatedParcelType": "SIZE_A",
70    "recipient": {
71        "name": "John Doe",
72        "email": "test@instabee.com",
73        "phone": "0701234567",
74        "street": "Hälsingegatan 40",
75        "street2": "Floor 10",
76        "city": "Stockholm",
77        "postalCode": "11353",
78        "countryCode": "SE",
79        "coordinates": {
80            "lat": 59.343971,
81            "lon": 18.060796
82        }
83    },
84    "sender": {
85        "name": "Merchant A",
86        "email": "merchant@instabee.com",
87        "city": "Stockholm",
88        "countryCode": "SE"
89    }
90}