Listing Availability

​

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 falls in the listing’s available date ranges, its start and end times are allowed, and it 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, and 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, and 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.

​

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): 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.

​

What wins when a listing carries several constraints

Nothing overrides anything. The layers are combined with AND, so the tightest one decides and the others cannot widen it. A date range does not open a day the location is closed on, and opening hours do not open a day outside every range. Two kinds of rule make up the answer, and knowing which is which explains what the endpoints report: The per-weekday start and end times are part of the availability answer, so the calendar closes a weekday that allows no start. The booking interval is not: treat it as the grid a picker draws from, since the availability endpoints accept an off-grid instant and admin order management books off the grid deliberately. The write-path checks behind all of this run on the storefront and checkout paths only. Admin order creation is exempt from the date ranges, the start and end times, the interval and the order deadline alike, so staff can take a booking on the phone that the storefront refuses. Every check gates a booking being created, so a rule changed today leaves yesterday’s orders valid and editable.

​

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

​

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. The two availability endpoints are part of the documented Admin API. The last two are reachable but are not published in the reference, so they can change without notice, so build on them only if you can absorb that. See the API reference for full parameters and response schemas. It is generated from the live API, so it always reflects the current fields.

​

Related articles