Listing Base Price Changed¶

Sent whenever a listing's effective base price changes — through the Partners API or any other Beyond surface. Use it to keep your own records in sync with the base price Beyond Pricing anchors its algorithm to. The enabled attribute tells you whether that price is live or still speculative.


Event type	`listing.base_price_changed`
Resource type	`listing-base-price-changed-events`
Triggered by	A change to a listing's effective base price (see below)

When It Fires¶

This event tracks the listing's effective base price — whichever value Beyond currently anchors its algorithm to. That is the user-set base price when one exists, and otherwise the starting base price Beyond's algorithm computes for the listing from its characteristics.

It fires whenever that effective price changes, in any code path — not only the Partners API. That includes:

The Base Price customization endpoint.
The Beyond web app.
Bulk edits and other internal tools.
A change to the algorithm's computed starting price, while no user base price is set.

Two rules narrow when the computed starting price fires:

It fires only on a change from one value to another. The first-ever price (null → a value) is a listing becoming ready for the first time and is delivered as listing.created instead, not here.
While a user base price is set, the computed starting price is dormant: its changes do not fire, and only user base-price changes do.

Changing the listing's currency also fires the event, even when the numeric base price is unchanged — a currency re-denomination counts as a base-price change.

Use the enabled attribute to tell a live change (enabled: true) from a speculative one (enabled: false). A change to the computed starting price always arrives with enabled: false, because a listing cannot be enabled until a user base price is set — so it signals a price Beyond is preparing, not one yet in effect.

The webhook is delivered to the OAuth2 application that owns the listing's user (User.owner_application). Listings owned by ordinary, non-API users have no owning application and produce no event.

Not the modeled nightly price

This event is about the base price — the user-set anchor Beyond's algorithm prices around — not the per-night recommended price. For nightly prices, read the calendar.

Payload¶

Price changeFirst time setComputed starting price (speculative)

{
  "meta": {
    "type": "listing.base_price_changed",
    "sent-at": "2026-07-03T14:05:00Z"
  },
  "data": {
    "type": "listing-base-price-changed-events",
    "id": "msg_01J9Z7Q1H4RM8ZW9P3D5C6B7E8",
    "attributes": {
      "new-base-price": 210,
      "old-base-price": 185,
      "new-currency": "USD",
      "old-currency": "USD",
      "changed-at": "2026-07-03T14:05:00Z",
      "channel-listings": [
        { "channel": "hostaway", "channel-id": "external-listing-987" }
      ],
      "enabled": true,
      "change-source": "user",
      "changed-by": "owner@example.com"
    },
    "relationships": {
      "listing": {
        "data": { "type": "listings", "id": "12345" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/listings/12345/" }
      },
      "user": {
        "data": { "type": "users", "id": "456" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/" }
      },
      "account": {
        "data": { "type": "accounts", "id": "789" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/accounts/789/" }
      }
    }
  }
}

{
  "meta": {
    "type": "listing.base_price_changed",
    "sent-at": "2026-07-03T14:05:00Z"
  },
  "data": {
    "type": "listing-base-price-changed-events",
    "id": "msg_01J9Z7Q1H4RM8ZW9P3D5C6B7E8",
    "attributes": {
      "new-base-price": 185,
      "old-base-price": null,
      "new-currency": "USD",
      "old-currency": null,
      "changed-at": "2026-07-03T14:05:00Z",
      "channel-listings": [
        { "channel": "hostaway", "channel-id": "external-listing-987" }
      ],
      "enabled": false,
      "change-source": "user",
      "changed-by": "owner@example.com"
    },
    "relationships": {
      "listing": {
        "data": { "type": "listings", "id": "12345" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/listings/12345/" }
      },
      "user": {
        "data": { "type": "users", "id": "456" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/" }
      },
      "account": {
        "data": { "type": "accounts", "id": "789" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/accounts/789/" }
      }
    }
  }
}

{
  "meta": {
    "type": "listing.base_price_changed",
    "sent-at": "2026-07-03T14:05:00Z"
  },
  "data": {
    "type": "listing-base-price-changed-events",
    "id": "msg_01J9Z7Q1H4RM8ZW9P3D5C6B7E8",
    "attributes": {
      "new-base-price": 195,
      "old-base-price": 180,
      "new-currency": "USD",
      "old-currency": "USD",
      "changed-at": "2026-07-03T14:05:00Z",
      "channel-listings": [
        { "channel": "hostaway", "channel-id": "external-listing-987" }
      ],
      "enabled": false,
      "change-source": "system",
      "changed-by": null
    },
    "relationships": {
      "listing": {
        "data": { "type": "listings", "id": "12345" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/listings/12345/" }
      },
      "user": {
        "data": { "type": "users", "id": "456" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/" }
      },
      "account": {
        "data": { "type": "accounts", "id": "789" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/accounts/789/" }
      }
    }
  }
}

The meta envelope is documented in the Payload Envelope section.

`data.attributes`¶

Field	Type	Description
`new-base-price`	integer	The listing's new base price, in the listing currency — the same whole number the listing resource exposes as `base-price` (fractional amounts are truncated toward zero).
`old-base-price`	integer \| null	The previous base price as a whole number, or `null` the first time a base price is set on the listing.
`new-currency`	string \| null	ISO 4217 currency code the new base price is denominated in.
`old-currency`	string \| null	ISO 4217 currency code of the previous base price. Differs from `new-currency` only on a currency re-denomination; equal to it for a plain price change.
`changed-at`	string (RFC 3339) \| null	UTC timestamp when the base price changed.
`channel-listings`	array of objects	The listing's active channel listings — one entry per channel the listing is syndicated to, the same `channel-listings` exposed on the listing resource. Empty (`[]`) on the rare listing with no active channel listing. Each entry has `channel` (the channel, e.g. `airbnb`, `hostaway`) and `channel-id` (the listing's identifier on the channel side, for correlating the event with your own records).
`enabled`	boolean	Whether the listing has pricing enabled. `true` means the change is live; `false` means it is speculative — e.g. a change to the algorithm's computed starting price (always `false`), or a user editing the base price before turning syncing on.
`change-source`	string (`user` \| `system`)	What moved the base price. `user` — an authenticated actor made the change (the Partners API, the Beyond app, or an admin). `system` — an automatic process made it (Beyond's algorithm computing a starting price, a scheduled auto-approved booking review, a background job). A change to the computed starting price is always `system`. Note this reflects who was authenticated, not who computed the value: a person accepting a Beyond-generated recommendation is `user`.
`changed-by`	string \| null	Email of the individual who made a `user` change. `null` whenever no individual is responsible: every `system` change, and any `user` change made by a machine — an app-level (`client_credentials`) Partners API token acts for the account as a whole, not for a person, so it names nobody. Changes made by Beyond staff on your behalf report `support@beyondpricing.com` rather than an internal address.

`data.relationships`¶

Every relationship carries a links.related URL you can GET for the current state of the related resource.

Relationship	Description
`listing`	The Beyond Pricing master listing whose base price changed (`{ "type": "listings", "id": … }`).
`user`	The user who owns the listing (`{ "type": "users", "id": … }`).
`account`	The managed account the listing's primary channel listing belongs to (`{ "type": "accounts", "id": … }`). Omitted on the rare listing with no active channel listing.

Handling Tips¶

Treat old-base-price: null as "base price set for the first time" rather than a decrease from zero.
Branch on enabled to decide how to react: enabled: true is a price that is live now; enabled: false is speculative (the algorithm's computed starting price, or a pre-enable edit) and you may want to stage rather than apply it. A change to the computed starting price always arrives with enabled: false.
Compare old-currency and new-currency to tell a currency re-denomination apart from a plain price change: when they differ, the numeric value moved because the currency changed, not because the price was re-negotiated.
Branch on change-source to tell an actor-initiated change (user) from an automatic one (system) — e.g. to skip mirroring Beyond's own algorithmic adjustments, or to only react to human-driven edits. It reflects who was authenticated, not who computed the value.
Use changed-by to attribute a user change to a person, but do not treat a null as "no one did it": edits made through an app-level Partners API token are change-source: user with changed-by: null, because the token acts for the account rather than for an individual.
Because this event fires from every surface, expect changes made in the Beyond app or by bulk operations, not only ones your integration initiated. Dedupe on webhook-id (see idempotency) since retries re-use it.
Follow the listing.links.related URL to fetch the listing's current representation rather than assuming its contents from this event.