Skip to main content

​
Definition

Availability answers one question — which listings can a customer get in this sales channel? — and lets you deepen it with context:
  • …with a given fulfillment type
  • …at a specific location
  • …to be booked between two dates
The same availability service powers TWICE’s own sales channels (Online Store, POS, Admin) and is available to external integrations through the API.

​
How it works

Availability is not binary — whether a listing is available depends on several factors, which layer on as you add context:
  • Listing — the listing is active, visible in the channel, and has at least one valid purchase type.
  • Stock — at least one location holds stock (for items that track inventory).
  • Fulfillment — a fulfillment method can serve the customer. For in-store pickup, a listing is eligible at a Location only when it’s sold there and that Location’s fulfillment rules offer in-store pickup for the listing’s purchase type (rental or sale).
  • Dates — for bookings, the requested period is free of conflicts on the calendar.
A customer usually chooses a location and dates late in the journey, so availability answers with whatever context it has and gets more precise as context is added:

​
Eligibility vs. availability

Two of these factors answer different questions, and the storefront resolves them in order:
  • Eligibility is a configuration fact — can this listing be fulfilled at this Location at all? A Location is eligible for a listing when the listing is sold there and the Location offers a fulfillment method for the listing’s purchase type. It doesn’t depend on stock levels or dates, so it can be evaluated up front — to show “available for pickup at these Locations” and to filter the Location picker.
  • Availability layers stock and dates on top — do the eligible Locations actually have the requested items free for the chosen period? A Location can be eligible but still out of stock for a given range or quantity.
The storefront narrows to eligible Locations first, then resolves real stock and dates for the Location the customer selects. So an item shown as “available for pickup” can still come back as out of stock once concrete dates and quantities are applied — eligibility says where it could be fulfilled, availability confirms whether it can be, right now. On multi-location storefronts, the store selector drives which Location’s stock the customer sees. The cart page extends this with a per-store availability check — each store is marked “Cart available” or “Cart unavailable” based on whether it can fulfill every item in the cart for the selected dates.

​
Availability signal vs. exact stock

For a browse view, availability is a signal — available somewhere — rather than a count. It tells the customer whether an item can be bought and at how many locations, without exposing exact quantities: Exact per-location quantities are returned only once a specific location is selected, and only when the merchant chooses to show them — some merchants want a “only 2 left” scarcity cue, while others treat exact stock as private. For bookable items, availability is inherently date-based: there is no meaningful signal until the customer picks dates.
Availability reflects Stock Item state and any scheduled events (reservations and other holds) that block an item for a period. An item that is committed to an order, reserved, or not In use does not count toward availability for that range. Buffer time also extends the unavailable window in both directions — a pre-booking buffer blocks the item before the booking starts (and acts as a minimum lead time on the storefront), while a post-booking buffer blocks it after the booking ends. Both buffered periods count as committed and prevent the item from being booked during those windows.

​
The booking decision

Whether a customer can get a listing is an AND across several layers — each must pass, and the first layer that fails is the reason it isn’t offered. The storefront evaluates them from cheapest (pure configuration) to most specific (live stock and dates):
1

The listing is sellable

  • Active status — Draft and template Listings are never offered.
  • Enabled in the customer’s sales channel (salesChannelOnline for the Online Store).
  • Has at least one purchase type with a row in an attached Price Table: an enabled, in-window booking row for rentals, or a sales row for purchases.
2

A location can fulfill it — *eligibility*

  • The listing is sold at the Location (linked), and the Location is active with the channel enabled.
  • The Location’s fulfillment rules offer the requested fulfillment method (e.g. in-store pickup) for that purchase type. A store that offers pickup for sales but not rentals makes a rental ineligible there — even if it’s in stock.
This layer is pure configuration: no stock or dates are consulted yet, so it can be resolved up front to filter the Location picker.
3

There is stock — *availability*

For inventory-tracked items, an eligible Location must hold at least one usable Stock Item — In use, and not committed to an order, reserved, or otherwise held. Listings with unlimited availability skip this layer.
4

The dates and quantity fit (bookings)

Once the customer picks a period:
  • A booking row must cover the duration and respect its weekdays and timeOfDayRange, the table’s date window, and the listing’s min / max booking duration — otherwise there’s no price, so no bookable option.
  • The Location’s fulfillment hours must allow the chosen pickup and return times. Pickup hours constrain the booking start; return hours constrain the booking end. Locations without custom fulfillment hours fall back to opening hours.
  • Every unit needed must be free of conflicts for the whole range — the requested quantity can’t exceed the units available across that period. Buffer time extends the conflict window in both directions — a before-buffer blocks the item before the booking start, and an after-buffer blocks it after the booking end. An item with a 1-hour before-buffer and a 2-hour after-buffer is unavailable from 1 hour before pickup through 2 hours after return. One reservation is left out of this check: the one held by the line item you are editing — see Editing an existing line item.
  • A stock item’s before-buffer also enforces a minimum lead time on the storefront: a booking starting sooner than the buffer allows is shown as unavailable. Admin staff are exempt from this restriction.
5

The order deadline has not passed (bookings & subscriptions)

If the listing has an order deadline, the customer must place the order before the cutoff:
  • A set time before — the start time minus a fixed offset (e.g. 2 hours before start).
  • By time of day — a wall-clock cutoff on an earlier day, resolved in the service location’s timezone (e.g. by 18:00, 1 day before start).
Start times past their deadline appear as unavailable on the storefront calendar. If a customer has an item in the cart and the deadline passes before checkout, the cart flags the item with an order_deadline notice. Admin users are exempt — staff can create orders past the deadline.
The customer-facing answer reflects the deepest layer reached: “Available at 3 locations” before a Location is chosen, “Not available from this location” when eligibility fails there, “No available days” when no date passes, and a unit count like “Only 1 left” when quantity is the blocker.

​
Editing an existing line item

When availability is computed for a line item that is being edited, that line item’s own reservation is excluded from the check, along with the reservations of any add-ons attached to it. The exclusion covers the whole reserved footprint — buffer windows included — so a line item never blocks its own edit. Without it, an item’s own buffer would count against it: a stock item with a 2-hour after-buffer would refuse a 1-hour extension of the very rental period that created that buffer. Excluding a sold stock item frees the capacity that sale consumed in the same way, so re-dating a sale sees its own unit as available again. The rule applies wherever an existing line item is re-dated or re-picked — the admin’s line item editor, and the storefront cart’s edit flow. It does not extend to other line items on the same order: those hold their reservations normally, and an edit that collides with one is reported as unavailable.

​
Items already in the cart

Items in the cart are checked as if they were already booked, buffers and all. A second rental of the same stock item that starts inside the first one’s after-buffer is not offered, even when the two rental periods themselves do not overlap. The same applies across the cart page’s per-store check: a store counts as “Cart available” only when it can hold every item in the cart, each with its buffer windows, at the same time.

​
Examples

The listing is active and in stock at the store, but the store’s fulfillment rules enable in-store pickup for sales only. The rental is ineligible there, so the storefront shows “Not available from this location” — even though units exist. It can still be bookable at another store that offers rental pickup.
The item is eligible and has units, but every unit at the selected Location is already committed for part of the requested period. It reads as available in the browse signal, yet the calendar returns no bookable range for those exact dates — different dates or a different Location resolve it.
A stock item carries a 2-hour after-buffer, and a customer calls to extend their rental by an hour. The extra hour falls inside the buffer the rental itself created. Because the line item being edited is excluded from the check, the hour reads as free and the new dates save. Another customer’s booking in that same window would still block it.
The only booking row is restricted to Mon–Fri (weekdays) with a two-day minimum. A Saturday start, or a one-day booking, matches no row — no price, so it isn’t bookable for that selection even though stock is free.The storefront surfaces this before the customer commits: in the booking widget’s Booking options dropdown, an option that can’t start on the selected date is greyed and captioned with the next date it can — “Not available for selected dates — next available Mon 18.8”. Selecting it moves the start date to that day. See Booking options and the selected date.
The customer wants 3 units; the selected Location has 1 free for the range and another has 2. Neither can fulfill all 3 alone, so the item shows as available overall but the selected Location caps at 1. Lowering the quantity — or choosing a Location with enough stock — resolves it.
A made-to-order sale listing with unlimited availability skips the stock and conflict layers entirely: as long as it’s active, in-channel, and sold at an eligible Location, it’s purchasable with no quantity ceiling.
A listing has a “2 hours before start” order deadline. A customer adds a 14:00 booking to their cart at 11:30, but doesn’t check out until 12:15. The cart flags the item — the deadline was 12:00, and the order can no longer be placed for that start time. The customer can pick a later start time or remove the item.

​
Querying availability via the API

Authenticate with the X-API-KEY header (see API Keys). The main endpoints: Common query parameters include from / to (the date range), serviceLocationIds, and variantValueIds. Storefront-facing equivalents live under /storefront/catalog/products/{productId}/availability/period and /range. See the API reference for full parameters and response schemas — it is generated from the live API, so it always reflects the current fields.

Listings

The customer-facing catalog entity availability is evaluated for.

Stock Item State

In / Out commitments that drive what’s available.

Scheduled Events

Reservations and holds that block availability for a period.

Price Tables

Pricing returned alongside availability for bookings.

Locations

Where listings are sold and the fulfillment rules that drive pickup eligibility.