Headless API

If our widget isn't applicable to your store (for example, if you're building a custom storefront or a mobile app), you have the ability to build your own date/time slot selector using the following endpoints.

Get the available dates

This endpoint returns all the available dates based on your shop's settings. Optionally, you can all so get the time slots along with the dates.

GET https://datepicker.buunto.com/api/v1/available_dates

Example response body:

{
    "LOCAL_DELIVERY": [{
        date: "2022-10-20",
        soldOut: false,
        remaining: 2,
        formatted: "20 October 2022"
    }, {
        date: "2022-10-21",
        soldOut: false,
        remaining: 5,
        formatted: "21 October 2022"
    }],
    "STORE_PICKUP": [{
        date: "2022-10-19",
        soldOut: false,
        remaining: 10,
        formatted: "19 October 2022"
    }, {
        date: "2022-10-20",
        soldOut: false,
        remaining: 10,
        formatted: "20 October 2022"
    }, {
        date: "2022-10-21",
        soldOut: false,
        remaining: 8,
        formatted: "20 October 2022"
    }]
}

Retrieves all the available dates for the shop.

There can be different available dates depending on the delivery method ( LOCAL_DELIVERY      or STORE_PICKUP      ). If you're not using the method selector then all the dates will be under LOCAL_DELIVERY      .

Note: When locations are enabled for a delivery method (e.g. LOCAL_DELIVERY    or STORE_PICKUP   ), the response may include location data. You can pass an optional locationId    parameter to filter available dates and time slots for a specific location and to resolve location-specific remaining capacity.

Each date is an object with 3 properties:

• date      - Date with ISO format
• formatted      - Date formatted based on the shop's locale for both display and value
• soldOut      - When using the order limit feature this value turns true      when the limit has been reached for that date
• remaining      - Optional remaining capacity for that date. This is returned when daily order limits are enabled and Buunto can resolve the correct settings for the request. If your setup uses location-specific settings or location-based daily limits, pass locationId      to receive this value.
• timeSlots      - This property will only be shown when the parameter withTimeSlots      is true      . It's an array listing all the time slots for that date. Please refer to the available_time_slots      for more information about the format.

Example response body when withTimeSlots      is true      :

{
    "LOCAL_DELIVERY": [{
        date: "2022-10-21",
        soldOut: false,
        remaining: 6,
        formatted: "20 October 2022",
        timeSlots: [{
            "to": "11:00",
            "from": "10:00",
            "formatted": "10:00 - 11:00",
            "disabled": true,
            "soldOut": false,
            "remaining": 2
        }, {
            "to": "12:00",
            "from": "11:00",
            "formatted": "11:00 - 12:00",
            "disabled": true,
            "soldOut": false,
            "remaining": 1
        }]
    }]
}

Get the available times

This endpoint returns all the available times based on your shop's settings for a given date and delivery method.

GET https://datepicker.buunto.com/api/v1/available_time_slots

Retrieves all timeslots for the provided date and method.

Example response body:

[{
    "to": "11:00",
    "from": "10:00",
    "formatted": "10:00 - 11:00",
    "disabled": true,
    "soldOut": false,
    "remaining": 2
}, {
    "to": "12:00",
    "from": "11:00",
    "formatted": "11:00 - 12:00",
    "disabled": true,
    "soldOut": false,
    "remaining": 1,
}, {
    "to": "13:00",
    "from": "12:00",
    "formatted": "12:00 - 13:00",
    "disabled": true,
    "soldOut": true,
    "remaining": 0
}]

Each time slot is an object with 5 properties:

• from  and to  - Start and end of the time slot formatted as HH:MM
• formatted  - Time slot formatted based on the shop's locale for both display and value. This value must be attached to the order for Buunto's backend to parse the date correctly.
• disabled  - true      when the option should be disabled. For example when it's past the preparation time cutoff.
• soldOut  - When using the order limit feature this value turns true  when the limit has been reached for that time slot.
• remaining  - Optional remaining capacity for that time slot. This is returned when time slot order limits are enabled and Buunto can resolve the correct settings for the request. If your setup uses location-specific settings or location-based limits, pass locationId  to receive this value.

Get the cut-off times

This end point returns the first available date and its cut-off time for each delivery method.

GET https://datepicker.buunto.com/api/v1/cut_off_times

Example response body:

{
  "LOCAL_DELIVERY": {
    "firstAvailableDate": "2025-03-03",
    "cutOffTime": "2025-03-01T12:00:00+00:00"
  },
  "STORE_PICKUP": {
    "firstAvailableDate": "2025-03-01",
    "cutOffTime": "2025-02-28T18:00:00+00:00"
  }
}

Save the customer's selection

Once the customer has picked a date, save it on the Shopify cart so Buunto can record the order and, when Checkout Validation is enabled, check the date at checkout. With the Storefront API, use cartAttributesUpdate  when the date picker is set to show on the cart page. When it's set to show on the product page, add the same attributes to the product's cart line instead (cartLinesAdd  or cartLinesUpdate ).

Order attributes

Buunto reads these attributes to tag the order and count order limits. Their names are the labels set in your Buunto messages, in the customer's language (for example Delivery Date  and Delivery Time  in English).

• Date: the formatted  value returned by available_dates .
• Time slot: the formatted  value returned by available_time_slots .
• Method: the method's label as shown in the widget. Only needed when you offer several delivery methods.

The easiest way to get the exact names and values is to place a test order with the Buunto widget and copy the attributes from the order's Additional details.

Checkout validation attribute

When Checkout Validation is enabled, Buunto checks the selection stored in the __buunto_selection  attribute. Set it in the same place as the order attributes above. Its value is made of four fields separated by | :

METHOD|DATE|TIME_SLOT|LOCATION_ID

• METHOD : LOCAL_DELIVERY , STORE_PICKUP  or SHIPPING .
• DATE : the date  value returned by available_dates  (YYYY-MM-DD).
• TIME_SLOT : the time slot's from  and to  values joined by " - ", for example 10:00 - 11:00 . Leave it empty when there's no time slot.
• LOCATION_ID : the location ID you pass as locationId . Leave it empty when you don't use locations.

Examples:

LOCAL_DELIVERY|2026-10-20|10:00 - 11:00|
STORE_PICKUP|2026-10-21||123456789

If the attribute is missing or the date is no longer available, checkout shows an error and the customer can't complete the order.

Skipping checkout validation

To let a cart through checkout without a selection, set __buunto_selection  to |||||SKIP_VALIDATION . This only works when the date picker is set to show on the cart page.