Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsPreview Revenue Rules
Search the full API reference Esc to close

Preview Revenue Rules

Pricing & rates · REST API reference

Get support
POST/v1/facilities/{facility_id}/revenue-rules/preview
Each unit group of the facility as the saved rules price it today and with the draft saved as well. Nothing is written and nothing is locked.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/revenue-rules/preview' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "replaces_rule_id": "00000000-0000-4000-8000-000000000001",
  "rule": {
    "rule_type": "street",
    "trigger_kind": "always",
    "adjust_amount": 0,
    "adjust_direction": "increase",
    "adjust_unit": "percent",
    "facility_ids": [
      "00000000-0000-4000-8000-000000000001"
    ],
    "name": "Preview",
    "promotion_id": "00000000-0000-4000-8000-000000000001",
    "repeats_yearly": false,
    "scope_feature_name": "string",
    "scope_group_ids": [
      "00000000-0000-4000-8000-000000000001"
    ],
    "scope_kind": "all"
  }
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

facility_idpath · stringrequired

Format: uuid

Request body

application/json · Required

replaces_rule_idstring | null

A saved rule the draft replaces, so an edit is not counted twice.

Format: uuid

Show replaces_rule_id schema
string | null

A saved rule the draft replaces, so an edit is not counted twice.

Variant 1: string
string
Variant 2: null
null
ruleRevenueRuleDraftRequest | null

The draft rule; omit to preview the saved rules.

Show rule schema
RevenueRuleDraftRequest | null

The draft rule; omit to preview the saved rules.

Variant 1: RevenueRuleDraftRequest
adjust_amountnumber | string | null

Size of the adjustment: a percentage of at most 50, or a dollar amount.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)

Show adjust_amount schema
number | string | null

Size of the adjustment: a percentage of at most 50, or a dollar amount.

Variant 1: number
number
Variant 2: string
string
Variant 3: null
null
adjust_directionstring | null

Raise or lower the rate (price rules only).

Values: "increase", "decrease"

Show adjust_direction schema
string | null

Raise or lower the rate (price rules only).

Variant 1: string
string

Values: "increase", "decrease"

Variant 2: null
null
adjust_unitstring | null

percent or dollar; web rules take percent only.

Values: "percent", "dollar"

Show adjust_unit schema
string | null

percent or dollar; web rules take percent only.

Variant 1: string
string

Values: "percent", "dollar"

Variant 2: null
null
facility_idsstring[] | null

Facilities the draft would cover, as on create: omitted means the facility in the path, an empty list every facility. Its unit groups and promotion are checked against all of them; only the facility in the path is previewed.

Show facility_ids schema
string[] | null

Facilities the draft would cover, as on create: omitted means the facility in the path, an empty list every facility. Its unit groups and promotion are checked against all of them; only the facility in the path is previewed.

Variant 1: string[]
string[]
Variant 2: null
null
namestring

Optional while drafting.

Default: "Preview" · Max length: 100

promotion_idstring | null

The promotion a promotion rule switches on.

Format: uuid

Show promotion_id schema
string | null

The promotion a promotion rule switches on.

Variant 1: string
string
Variant 2: null
null
repeats_yearlyboolean

Repeat the date window every year by month and day.

Default: false

rule_typestringrequired

street and seasonal rules adjust the street rate, web rules the online discount; a promotion rule switches a promotion on. competitive is reserved and refused.

Values: "street", "seasonal", "web", "promotion", "competitive"

scope_feature_namestring | null

The characteristic, for the characteristic scope. Case and spacing are ignored.

Max length: 100

Show scope_feature_name schema
string | null

The characteristic, for the characteristic scope. Case and spacing are ignored.

Variant 1: string
string
Variant 2: null
null
scope_group_idsstring[] | null

The unit groups, for the groups scope.

Show scope_group_ids schema
string[] | null

The unit groups, for the groups scope.

Variant 1: string[]
string[]
Variant 2: null
null
scope_kindstring

Which unit groups the rule considers: all, the listed groups, or a characteristic.

Default: "all" · Values: "all", "groups", "characteristic"

statusstring

active applies the rule; paused keeps it without applying it.

Default: "active" · Values: "active", "paused"

threshold_pctnumber | string | null

Occupancy percentage, for the occupancy triggers.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,6}0*$)\d{0,3}\.\d{0,2}0*$)

Show threshold_pct schema
number | string | null

Occupancy percentage, for the occupancy triggers.

Variant 1: number
number
Variant 2: string
string
Variant 3: null
null
trigger_kindstringrequired

When the rule applies: always, while occupancy is below or above a threshold, or in a date window.

Values: "always", "occupancy_below", "occupancy_above", "date_window"

window_endstring | null

Last day of the date window, inclusive.

Format: date

Show window_end schema
string | null

Last day of the date window, inclusive.

Variant 1: string
string
Variant 2: null
null
window_startstring | null

First day of the date window, inclusive.

Format: date

Show window_start schema
string | null

First day of the date window, inclusive.

Variant 1: string
string
Variant 2: null
null
Variant 2: null
null

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": {
    "as_of": "2026-10-29",
    "band_pct": "<VALUE_MATCHING_PATTERN>",
    "draft_group_count": 0,
    "facility_id": "00000000-0000-4000-8000-000000000001",
    "groups": [
      {
        "code": "string",
        "draft_applies": false,
        "feature_names": [
          "string"
        ],
        "id": "00000000-0000-4000-8000-000000000001",
        "managed_after": false,
        "managed_now": false,
        "name": "string",
        "occupancy_pct": "<VALUE_MATCHING_PATTERN>",
        "promotion_ids_after": [
          "00000000-0000-4000-8000-000000000001"
        ],
        "promotion_ids_now": [
          "00000000-0000-4000-8000-000000000001"
        ],
        "street_after": "<VALUE_MATCHING_PATTERN>",
        "street_now": "<VALUE_MATCHING_PATTERN>",
        "web_after": "<VALUE_MATCHING_PATTERN>",
        "web_now": "<VALUE_MATCHING_PATTERN>"
      }
    ],
    "groups_moving": 0
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataRevenueRulePreviewResponserequired

What a draft rule would change at one facility, against the saved rules as they evaluate today. Nothing was written and nothing was locked.

Show data schema
as_ofstringrequired

The facility-local date the conditions were read on.

Format: date

band_pctstringrequired

How far rules may move a rate from its base, in percent, without a floor or ceiling.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

draft_group_countintegerrequired

Groups the draft rule would apply to.

facility_idstringrequired

The facility previewed.

Format: uuid

groupsRevenueRulePreviewGroup[]required

Every live unit group of the facility.

Show groups schema
codestring | nullrequired

The group's code, where it has one.

Show code schema
string | null

The group's code, where it has one.

Variant 1: string
string
Variant 2: null
null
draft_appliesbooleanrequired

Whether the draft rule applies to this group.

feature_namesstring[]required

The group's characteristics.

Show feature_names schema
string
idstringrequired

The unit group's id.

Format: uuid

managed_afterbooleanrequired

Whether a rule would move them with the draft saved as well.

managed_nowbooleanrequired

Whether a saved rule moves this group's rates today.

namestringrequired

The group's name.

occupancy_pctstring | nullrequired

The occupancy rules compare against; null with no countable units.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show occupancy_pct schema
string | null

The occupancy rules compare against; null with no countable units.

Variant 1: string
string
Variant 2: null
null
promotion_ids_afterstring[]required

Promotions rules would switch on with the draft saved as well.

Show promotion_ids_after schema
string
promotion_ids_nowstring[]required

Promotions the saved rules switch on for this group today.

Show promotion_ids_now schema
string
street_afterstring | nullrequired

Effective street rate with the draft saved as well.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show street_after schema
string | null

Effective street rate with the draft saved as well.

Variant 1: string
string
Variant 2: null
null
street_nowstring | nullrequired

Effective street rate under the saved rules with today's occupancy and date (tonight's value).

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show street_now schema
string | null

Effective street rate under the saved rules with today's occupancy and date (tonight's value).

Variant 1: string
string
Variant 2: null
null
web_afterstring | nullrequired

Effective online rate with the draft saved as well.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show web_after schema
string | null

Effective online rate with the draft saved as well.

Variant 1: string
string
Variant 2: null
null
web_nowstring | nullrequired

Effective online rate under the saved rules today.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show web_now schema
string | null

Effective online rate under the saved rules today.

Variant 1: string
string
Variant 2: null
null
groups_movingintegerrequired

Groups whose street or online rate the draft changes.

metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Preview Revenue Rules | Facily Developers