Listings¶

Listings are the properties Beyond prices. Every other listing-scoped resource — calendar, recommendations, customizations, market insights — hangs off a listing id from this endpoint.

Endpoint	Method	Scope	Description
`/api/v1/listings/`	GET	`listings:read`	List all listings (paginated)
`/api/v1/listings/<id>/`	GET	`listings:read`	Get listing details
`/api/v1/listings/<id>/activation/`	PATCH	`listings:write`	Enable or disable price syncing for a listing
`/api/v1/listings/<id>/refresh/`	POST	`listings:write`	Queue a full refresh (listing details and reservations) for a listing
`/api/v1/listings/<id>/customizations/<type>/`	GET, PATCH	`listings:read`, `listings:write`	Retrieve or update listing customizations

Try it out

Explore parameters, schemas, and live requests in the Swagger UI.

List Listings¶

Returns a paginated list of all listings for the authenticated application.

Request¶

GET /api/v1/listings/
    ?filter[enabled]=true
    &sort=-created-at
    &page[size]=25

Parameter	Description
`filter[owner]`	Only listings owned by this user id.
`filter[enabled]`	Only listings with price syncing enabled (`true`) or disabled (`false`).
`filter[name]`	Only listings whose title contains this text (case-insensitive).
`filter[market]`	Only listings in this Beyond market (case-insensitive exact match on the `market` attribute, e.g. `San Francisco`).
`filter[bedrooms]`	Only listings with exactly this bedroom count.
`filter[in-active-market]`	Only listings that are fully priceable (`true`) or not (`false`). Same semantics as the `in-active-market` attribute.
`sort`	Sort field: `created-at`, `title`, or `city`. Prefix with `-` for descending. Default `-created-at` (newest first).
`include`	Sideload related resources: `owner`. See Compound documents.
`page[number]`, `page[size]`	Standard pagination. Default page size 25, maximum 100.

Response¶

{
  "data": [
    {
      "type": "listings",
      "id": "123",
      "attributes": {
        "title": "Sunny 2BR near the beach",
        "image": "https://images.example.com/listing-123.jpg",
        "neighborhood": "Mission District",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "market": "San Francisco",
        "room-type": "entire_home",
        "bedrooms": 2,
        "bathrooms": "1.50",
        "base-price": 189,
        "base-price-updated-at": "2026-07-02T09:15:00Z",
        "min-price": 95,
        "min-price-updated-at": "2026-07-02T09:15:00Z",
        "max-price": null,
        "min-stay": 2,
        "extra-guest-fee": 25,
        "extra-guest-threshold": 4,
        "latitude": "37.77490000",
        "longitude": "-122.41940000",
        "timezone": "America/Los_Angeles",
        "currency": "USD",
        "in-active-market": true,
        "enabled": true,
        "address": "123 Main St, San Francisco, CA",
        "created-at": "2026-05-20T18:03:11Z",
        "channel-listings": [
          {"channel": "airbnb", "channel-id": "987654321"}
        ]
      },
      "relationships": {
        "owner": {"data": {"type": "users", "id": "456"}}
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Listing attributes¶

Field	Description
`title`, `image`, `address`, `neighborhood`, `city`, `state`, `country`	Descriptive metadata synced from the channel/PMS.
`market`	The Beyond market the listing belongs to (e.g. `San Francisco`); `null` while unassigned. Filterable via `filter[market]`.
`room-type`	Property type as reported by the channel (e.g. `entire_home`).
`bedrooms`	Bedroom count.
`bathrooms`	Bathroom count, as a decimal string — `"1.50"` is one full and one half bath.
`base-price`	The listing's nightly base price in `currency` — the anchor Beyond's algorithm prices around. Managed via the base-price customization.
`base-price-updated-at`, `min-price-updated-at`	When the respective price was last changed.
`min-price`, `max-price`	The listing-level nightly floor and ceiling in `currency`. `max-price` is `null` when no ceiling is set. Managed via the min-max-prices customization.
`min-stay`	Default minimum stay, in nights.
`extra-guest-fee`, `extra-guest-threshold`	Per-guest fee in `currency` charged above the included guest count.
`latitude`, `longitude`	Coordinates, as decimal strings.
`timezone`	IANA timezone name. Date defaults on the calendar endpoint are computed in this timezone.
`currency`	ISO 4217 code the listing's prices are quoted in. Not necessarily the owner's billing currency, which is what market insights rates use.
`in-active-market`	Whether the listing is fully priceable. See Pricing readiness.
`enabled`	Whether price syncing is on. Change it via listing activation.
`created-at`	When the listing was created in Beyond.
`channel-listings`	The active channel listings linked to this listing, each with its `channel` (e.g. `airbnb`) and channel-side `channel-id`.

Get Listing Details¶

Returns detailed information about a specific listing. The detail response carries every list attribute above plus sync-status:

"sync-status": {
  "state": "completed",
  "last-successful-sync-at": "2026-08-09T04:12:44Z"
}

Field	Description
`sync-status.state`	Sync state of the primary channel listing: `queued`, `in_progress`, `completed`, or `unknown`.
`sync-status.last-successful-sync-at`	Timestamp of the last successful listing sync; `null` if never synced.

Pricing Readiness (`in-active-market`)¶

The in-active-market attribute tells you whether the listing is fully priceable: Beyond has assigned it to a pricing cluster and the cluster's market is active. Most listings are assigned a cluster as part of the initial import; occasionally one is created without a cluster, and in-active-market stays false until Beyond assigns one. A common cause is a wrong or imprecise listing address that lands the property outside any area Beyond covers (for example in the middle of the ocean) — correcting the address in the PMS lets the next sync cluster it. While the listing has no cluster, the Calendar endpoint returns a 400 ("not yet clustered"). When in-active-market is true, the calendar endpoint is always available for the listing.

Once a listing has a base price, every later change of in-active-market — in either direction — is announced by the listing.in_active_market_changed webhook, so you never need to poll for it.

Compound Documents (Sideloading)¶

Include related resources in a single request using the ?include= parameter:

owner -- the user who owns the listing

This avoids a separate API call to fetch the owner. See the JSON:API guide for details on how compound documents work.

Listing Activation¶

Use the listing activation endpoint to enable or disable price syncing for a listing.

Newly synced listings are created disabled, so this is the endpoint used in the final step of the partner onboarding flow.

Request¶

PATCH /api/v1/listings/123/activation/

{
  "data": {
    "type": "listing-activations",
    "id": "123",
    "attributes": {
      "enabled": true,
      "base-price": 189,
      "min-price": 95
    }
  }
}

Field	Description
`enabled`	Required. Whether price syncing is enabled for the listing.
`base-price`	Nightly base price to apply with the activation, in the listing's `currency`. Minimum `10`. Required when enabling a listing that has no base price yet — omitting it is a `422` with code `required`.
`min-price`	Minimum nightly price to apply with the activation. Minimum `5`.

The response echoes the resulting activation state (enabled, base-price, min-price). Sending the state the listing is already in returns 304 Not Modified with no body.

Listing Refresh¶

Use the listing refresh endpoint to enqueue an asynchronous full refresh for a listing's primary channel listing. This refreshes the listing's details and availability, then its reservations, and finally recomputes the automatic base price.

Request¶

POST /api/v1/listings/123/refresh/

No request body. The endpoint returns immediately with 202 Accepted once the jobs are queued:

{
  "meta": {
    "status": "accepted",
    "message": "Listing refresh queued"
  },
  "links": {
    "related": "$BASE_URL/api/v1/listings/123/"
  }
}

When the refresh chain finishes (or fails), the listing.refreshed webhook reports the outcome — no polling needed.

Listing Customizations¶

Use the Listing Customizations endpoints to retrieve and update pricing and stay-rule settings for a specific listing.

Supported customization types include:

base-price
min-stays
extra-guest-fees
min-max-prices
time-based-adjustments
manual-overrides

You can also read every customization in one request with GET /api/v1/listings/<id>/customizations/.

Use cases¶

Initial import. Page through GET /listings/ after onboarding a user to discover the listings Beyond synced from their PMS, then store the ids for the per-listing endpoints.
Enable pricing selectively. Filter with filter[enabled]=false, review each listing's base-price, and PATCH its activation once the price is agreed with the owner.
Readiness gate. Before calling the calendar endpoint, check in-active-market — false predicts the calendar's "not yet clustered" 400.
Reconciliation. Match your PMS records to Beyond through channel-listings (channel + channel-id) rather than by title.

Errors¶

Status	Cause
`304`	Activation PATCH that does not change `enabled`.
`400`	Malformed filter, sort, or request body.
`401`	Missing or invalid bearer token.
`403`	Token lacks the required scope (`listings:read` / `listings:write`).
`404`	No listing with that id is visible to your application; for refresh, also a listing with no active channel listing.
`422`	Activation enabling a listing without a `base-price` (code `required`), or a customization write the pricing engine rejects.
`429`	Rate limit exceeded. See Rate Limiting.

Listings¶

List Listings¶

Request¶

Response¶

Listing attributes¶

Get Listing Details¶

Pricing Readiness (in-active-market)¶

Compound Documents (Sideloading)¶

Listing Activation¶

Request¶

Listing Refresh¶

Request¶

Listing Customizations¶

Use cases¶

Errors¶

Pricing Readiness (`in-active-market`)¶