List units
Present an API key (sb_live_… / sb_test_…), an OAuth2 access token, or a static token as a Bearer credential. The operator is implied by the credential; it is never in the path. Only a SHA-256 hash of an API key is stored server-side.
In: header
Query Parameters
Filter by archive state. OMITTED (the default) returns BOTH archived and live records — that default is deliberate and will not change, because flipping a list's default filter is a breaking change under docs/api/lifecycle.md. Pass false for live records only, or true to see just the archived ones.
Opaque pagination cursor from meta.cursor.next of the previous page. Do not construct or parse it.
Page size. Values above the maximum are clamped.
1 <= value <= 10025Pass true to return only stock that can actually be sold right now. This is NOT the same as status=available: a unit sitting at reserved whose hold has expired IS bookable (nothing flips status back on cancel or expiry, so the commerce rows are the truth), and one at available with a live allocation or an unexpired hold is NOT. Archived units, and units of an inactive or storefront-hidden type, are excluded. The set returned is exactly the set GET /availability counts as available for the same filters — the two share one SQL predicate, so they cannot drift. Opt-in on the exact string true; any other value leaves the listing un-narrowed.
Filter to a single site.
uuidFilter by unit type.
uuidFilter by unit status.
Value in
- "available"
- "reserved"
- "occupied"
- "maintenance"
- "overlocked"
- "unavailable"
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/units"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "object": "unit", "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811", "unit_type_id": "09feeea8-7692-422e-90f1-4a851084cb1a", "name": "string", "status": "available", "floor": "string", "building": "string", "list_price_minor": 0, "currency": "str", "attributes": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z", "rateable_value_minor": 0 } ], "meta": { "limit": 0, "cursor": { "next": "string", "has_more": true } }}{ "error": { "code": "unauthorized", "message": "Missing or invalid credential." }}{ "error": { "code": "insufficient_scope", "message": "The credential lacks a scope required by this endpoint." }}{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry after 7s." }}{ "error": { "code": "validation_error", "message": "string", "details": [ { "field": "string", "issue": "string" } ] }}