Build an hourly booking widget

The Methods app block already supports hourly booking when pickup or drop-off time selection is on for your store. Build a custom widget only when you need a UI the block can’t provide.

This guide builds a custom storefront widget that books rentals by the hour, with pickup and drop-off at a chosen time of day, in place of the Methods app block. It follows the same data flow the block uses: read the store’s time configuration, fetch availability, render date and time slots, then create an intent and add it to the cart. Everything runs through the Shopify app proxy, so requests go to the store’s own domain and Shopify signs them. You never send an API key.

Request shape

https://{shop_domain}/{proxy_path_prefix}/{path}

Prerequisites

Hourly booking needs two things to be true for the store:

The pick_up_drop_off_time_selection feature flag is on. Contact support from the app to turn it on.
The pickup or drop-off method has time selection turned on, with a window and an interval set under Logistics and locations.

When time selection is off, treat the booking as day based: a date with no time.

Read the time window configuration

The store’s logistics configuration is injected into the theme by the Supercycle Engine app embed, the same source the Methods block reads. There’s no separate endpoint, so read it from the page:

Read the configuration

const { deliveryMethods, returnMethods, defaultDeliveryMethodType, defaultReturnMethodType, locations } =
  window.supercycleAppEmbed.context.appSettings;

const pickUp  = deliveryMethods.find((m) => m.deliveryMethodType === "pick_up");
const dropOff = returnMethods.find((m) => m.returnMethodType === "drop_off");

Each pickup and drop-off entry carries:

boolean

Whether this leg offers time slots. When false, render a date only.

string

The daily window the slots span, as "HH:MM", for example "09:00" to "17:00".

integer

The slot step in minutes: 15, 30, or 60.

Generate slots by stepping from fromTime to toTime in timeIntervalMinutes increments. defaultDeliveryMethodType and defaultReturnMethodType tell you which legs to preselect.

Fetch availability

Use the Availability log endpoint rather than the per-day Availability timeline. It returns availability with time-of-day precision, which is what time slots need.

Availability log request

GET https://{shop_domain}/{proxy_path_prefix}/availability_log
      ?variant_shopify_id=44556677
      &delivery_method_type=pick_up
      &return_method_type=drop_off
      &location_id=12345

The occupancy array is a list of change points, not one entry per day. Each { at, available } entry means that from at onward, available items are free until the next entry. at is a shop-local timestamp with no offset (YYYY-MM-DDTHH:MM:SS). Use it as it is and don’t apply a time zone offset.The counts already include preparation and restock time. You can set a preparation time (before an item goes out again, for cleaning and checks) and a restock time (after it comes back) on the methods, in hours. An item returned at 2 pm with a 6-hour restock doesn’t free up until 8 pm, so a slot earlier that evening shows as unavailable. The widget doesn’t compute any of this. It honors the occupancy counts.

Availability is expensive to compute and is cached, so fetch it again only when the selected variant, delivery or return method, or location changes.

Gray out unavailable dates and times

For a candidate pickup instant (a date plus a slot time), the number of items available is the available value of the last occupancy entry whose at is at or before it. A slot is bookable only if items stay available across the whole window the customer is requesting.

Is a slot bookable

// occupancy: sorted ascending by `at` (treat as shop-local wall-clock)
function slotBookable(occupancy, startISO, endISO) {
  let level = 0;
  for (const { at, available } of occupancy) {
    if (at <= startISO) level = available;       // level entering the window
  }
  let min = level;
  for (const { at, available } of occupancy) {
    if (at > startISO && at < endISO) min = Math.min(min, available); // changes inside it
  }
  return min > 0;
}

Disable any date or time whose window returns false. Because the log is sparse, this is cheap to evaluate on the client.

Create the intent and add to cart

When the customer has chosen their window, create the intent with the Intent endpoint, passing the times of day alongside the date:

Create an intent

POST https://{shop_domain}/{proxy_path_prefix}/intents
Content-Type: application/json

{
  "variant_id": 44556677,
  "option": {
    "global_id": "gid://supercycle/CalendarRental::RentalPeriod/1",
    "params": {
      "rental_start": "2026-06-27",
      "arrive_by_time": "14:30",
      "return_by_time": "17:00",
      "delivery_method_type": "pick_up",
      "return_method_type": "drop_off",
      "location_id": 12345
    }
  }
}

string

Pickup time of day ("HH:MM") from your slot picker. This is what makes the booking hourly. Omit it when the leg’s allowTimeSelection is false to fall back to day-based booking.

string

Drop-off time of day ("HH:MM"). Omit it for day-based booking.

The response contains an attributes object. Pass it straight through as the cart line’s attributes when you add the variant to the cart. It carries the line item properties and the selling_plan. On a problem (variant or option not found, or the method not turned on) the endpoint returns 422 with { "error": "..." }. Show the message to the customer and block add to cart.

Availability log

Fetch a variant’s availability with time-of-day precision.

Intent

Create the intent that turns a cart line into a cycle.

Methods

Use the app block that already supports hourly booking.

Introduction

App blocks

Code snippets

Guides

Troubleshooting

Build an hourly booking widget

Prerequisites

Build the widget

Availability log

Intent

Methods

​Prerequisites

​Build the widget

​Related documentation

Availability log

Intent

Methods

Prerequisites

Build the widget

Related documentation