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.

A listing appears here only while it has at least one active channel listing — a live connection to the channel or PMS the property is syndicated to. Beyond neither prices nor syncs a listing without one, so it is invisible to the whole API: every listing-scoped endpoint answers 404 for it, exactly as it does for a listing your application does not own.

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/?sync-priority=normal

No request body. The endpoint accepts one optional query parameter:

Parameter	Description
`sync-priority`	Optional. `high` (the default) or `normal`. See Sync priority below. Any other value is a `400`.

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.

Sync priority¶

The sync-priority query parameter tells Beyond how soon the refresh should start.

Value	Effect	Use it when
`high`	Beyond starts the refresh as soon as it can.	Someone is waiting on the result, for example a user who just changed the listing in your PMS.
`normal`	The refresh can take longer to start when Beyond is busy.	You refresh many listings at once and none of them is urgent.

The parameter is optional. A request that leaves it out is treated as high.

Priority affects only how soon the refresh starts. Either value refreshes the same data and fires the same listing.refreshed webhook.

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, or an unknown `sync-priority` on a refresh.
`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.
`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¶

Sync priority¶

Listing Customizations¶

Use cases¶

Errors¶

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