/v1/facilities/{facility_id}/promotionsAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest 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 --request POST \
--url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/promotions' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"code": "string",
"name": "string",
"applicability_rules": {},
"applicable_unit_group_ids": [
"00000000-0000-4000-8000-000000000001"
],
"auto_apply": false,
"channel_ids": [
"00000000-0000-4000-8000-000000000001"
],
"description": "string",
"discount": {
"discount_type": "percentage",
"months": 1,
"value": 0
},
"existing_tenant_only": false,
"facility_ids": [
"00000000-0000-4000-8000-000000000001"
],
"hide_from_website": false,
"is_active": true
}'Parameters
facility_idpath · stringrequiredFormat: uuid
dry_runquery · booleanValidate and compose the response, then roll back; nothing is saved.
Default: false
Request body
application/json · Required
applicability_rulesobject | nullShow applicability_rules schema
object | nullVariant 1: object
objectVariant 2: null
nullapplicable_unit_group_idsstring[] | nullNull: every unit. Otherwise at least one unit group at a covered facility.
Show applicable_unit_group_ids schema
string[] | nullNull: every unit. Otherwise at least one unit group at a covered facility.
Variant 1: string[]
string[]Variant 2: null
nullauto_applybooleanDefault: false
channel_idsstring[]Lead channels offered it online. Empty: every channel. hide_from_website true: none.
Show channel_ids schema
stringcodestringrequiredShown on bills and receipts. Stored upper-cased; unique among live promotions at a facility.
Min length: 1 · Max length: 50
descriptionstring | nullMax length: 2000
Show description schema
string | nullVariant 1: string
stringVariant 2: null
nulldiscountWizardDiscountRequest | nullShow discount schema
WizardDiscountRequest | nullVariant 1: WizardDiscountRequest
discount_typestringrequiredfree_period is 100% off each month and takes no value.
Values: "percentage", "flat", "free_period"
monthsintegerrequiredHow many months, starting with month 1, the discount applies to.
Minimum: 1 · Maximum: 120
valuenumber | string | nullThe percentage, or the dollar amount, per month.
Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)
Show value schema
number | string | nullThe percentage, or the dollar amount, per month.
Variant 1: number
numberVariant 2: string
stringVariant 3: null
nullVariant 2: null
nullexisting_tenant_onlybooleanDefault: false
facility_idsstring[] | nullOmitted: the facility in the path. Empty: every facility (needs an org-wide grant).
Show facility_ids schema
string[] | nullOmitted: the facility in the path. Empty: every facility (needs an org-wide grant).
Variant 1: string[]
string[]Variant 2: null
nullhide_from_websitebooleanDefault: false
is_activebooleanDefault: true
max_usesinteger | nullMinimum: 1
Show max_uses schema
integer | nullVariant 1: integer
integerVariant 2: null
nullmin_available_unitsinteger | nullOnly offered while at least this many units of the group are free.
Minimum: 1 · Maximum: 1000
Show min_available_units schema
integer | nullOnly offered while at least this many units of the group are free.
Variant 1: integer
integerVariant 2: null
nullmin_stay_monthsinteger | nullStored and shown; early move-out clawback is a later step.
Minimum: 1 · Maximum: 120
Show min_stay_months schema
integer | nullStored and shown; early move-out clawback is a later step.
Variant 1: integer
integerVariant 2: null
nullmove_in_onlybooleanDefault: false
namestringrequiredMin length: 1 · Max length: 100
prepay_monthsinteger | nullMinimum: 1 · Maximum: 36
Show prepay_months schema
integer | nullVariant 1: integer
integerVariant 2: null
nullprepay_requiredbooleanDefault: false
priorityinteger | nullLower first; 0 is valid; null is last.
Minimum: 0 · Maximum: 10000
Show priority schema
integer | nullLower first; 0 is valid; null is last.
Variant 1: integer
integerVariant 2: null
nullrepeat_last_monthbooleanThe last schedule row repeats for as long as the lease runs.
Default: false
scheduleScheduleRowRequest[] | nullMax items: 120
Show schedule schema
ScheduleRowRequest[] | nullVariant 1: ScheduleRowRequest[]
amountnumber | string | nullFor flat rows: the dollar amount off that month.
Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)
Show amount schema
number | string | nullFor flat rows: the dollar amount off that month.
Variant 1: number
numberVariant 2: string
stringVariant 3: null
nulldiscount_typestringpercentage, flat (a dollar amount off) or none (an undiscounted month inside the schedule).
Values: "percentage", "flat", "none"
month_numberinteger1 is the billing period the promotion starts in.
Minimum: 1 · Maximum: 120
percentagenumber | string | nullFor percentage rows: above 0, at most 100.
Maximum: 100 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,6}0*$)\d{0,3}\.\d{0,2}0*$)
Show percentage schema
number | string | nullFor percentage rows: above 0, at most 100.
Variant 1: number
numberVariant 2: string
stringVariant 3: null
nullVariant 2: null
nullstackablebooleanDefault: false
valid_fromstring | nullFormat: date
Show valid_from schema
string | nullVariant 1: string
stringVariant 2: null
nullvalid_untilstring | nullFormat: date
Show valid_until schema
string | nullVariant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"active_group_ids": [
"00000000-0000-4000-8000-000000000001"
],
"applicability_rules": {},
"applicable_unit_group_ids": [
"00000000-0000-4000-8000-000000000001"
],
"auto_apply": false,
"channel_ids": [
"00000000-0000-4000-8000-000000000001"
],
"code": "string",
"created_at": "2026-10-29T12:00:00Z",
"current_uses": 0,
"description": "string",
"discount_summary": "string",
"existing_tenant_only": false,
"facility_ids": [
"00000000-0000-4000-8000-000000000001"
],
"governed_by_rules": false,
"has_attachments": false,
"hide_from_website": false,
"id": "00000000-0000-4000-8000-000000000001",
"is_active": false,
"live_attachment_count": 0,
"max_uses": 0,
"min_available_units": 0,
"min_stay_months": 0,
"move_in_only": false,
"name": "string",
"prepay_months": 0,
"prepay_required": false,
"priority": 0,
"repeat_last_month": false,
"schedule": [
{
"amount": "<VALUE_MATCHING_PATTERN>",
"discount_type": "string",
"month_number": 0,
"percentage": "<VALUE_MATCHING_PATTERN>"
}
],
"stackable": false,
"updated_at": "2026-10-29T12:00:00Z",
"valid_from": "2026-10-29",
"valid_until": "2026-10-29"
},
"meta": {
"request_id": "string"
}
}application/json
dataPromotionResponserequiredShow data schema
active_group_idsstring[]requiredThe live unit groups promotion rules switch it on for now, limited the same way: the listed facility's, the readable facilities', or every facility's.
Show active_group_ids schema
stringapplicability_rulesobject | nullrequiredStored operator rules; not evaluated.
Show applicability_rules schema
object | nullStored operator rules; not evaluated.
Variant 1: object
objectVariant 2: null
nullapplicable_unit_group_idsstring[] | nullrequiredUnit groups it applies to; null means every unit.
Show applicable_unit_group_ids schema
string[] | nullUnit groups it applies to; null means every unit.
Variant 1: string[]
string[]Variant 2: null
nullauto_applybooleanrequiredApplied automatically at move-in when it qualifies (move-in, a later step).
channel_idsstring[]requiredLead channels offered it online. Empty: every channel, unless hide_from_website.
Show channel_ids schema
stringcodestringrequiredShown on bills and receipts.
created_atstringrequiredWhen the promotion was created.
Format: date-time
current_usesintegerrequiredHow many leases it has been applied to.
descriptionstring | nullrequiredFree-text description.
Show description schema
string | nullFree-text description.
Variant 1: string
stringVariant 2: null
nulldiscount_summarystringrequiredServer-composed summary, e.g. "50% off month 1", "Months 2 and 4 free".
existing_tenant_onlybooleanrequiredOnly for tenants who already rent another unit.
facility_idsstring[]requiredFacilities the promotion covers. Empty means every facility.
Show facility_ids schema
stringgoverned_by_rulesbooleanrequiredTrue when an active promotion rule governs it: at the listed facility on a facility's list; at one or more of the facilities you can read on GET by id; anywhere otherwise. Where it is governed it is offered only on the unit groups its rules switched on.
has_attachmentsbooleanrequiredTrue once any lease has used it; the discount is then read-only.
hide_from_websitebooleanrequiredFor staff use; not advertised online.
idstringrequiredUnique identifier for this promotion.
Format: uuid
is_activebooleanrequiredWhether it is switched on, independent of its date window.
live_attachment_countintegerrequiredLeases carrying it now.
max_usesinteger | nullrequiredMaximum number of leases it may be applied to. Null means unlimited.
Show max_uses schema
integer | nullMaximum number of leases it may be applied to. Null means unlimited.
Variant 1: integer
integerVariant 2: null
nullmin_available_unitsinteger | nullrequiredOnly offered while at least this many units of the group are free (live count).
Show min_available_units schema
integer | nullOnly offered while at least this many units of the group are free (live count).
Variant 1: integer
integerVariant 2: null
nullmin_stay_monthsinteger | nullrequiredMinimum stay the promotion asks for, in months.
Show min_stay_months schema
integer | nullMinimum stay the promotion asks for, in months.
Variant 1: integer
integerVariant 2: null
nullmove_in_onlybooleanrequiredOnly at move-in; it cannot be applied to an existing lease.
namestringrequiredOperator-facing promotion name.
prepay_monthsinteger | nullrequiredMonths that must be prepaid, when prepay_required is true.
Show prepay_months schema
integer | nullMonths that must be prepaid, when prepay_required is true.
Variant 1: integer
integerVariant 2: null
nullprepay_requiredbooleanrequiredThe tenant must prepay to qualify.
priorityinteger | nullrequiredStack order: a lower number first, 0 valid, null last.
Show priority schema
integer | nullStack order: a lower number first, 0 valid, null last.
Variant 1: integer
integerVariant 2: null
nullrepeat_last_monthbooleanrequiredTrue when the last schedule row repeats for as long as the lease runs.
schedulePromotionScheduleRowResponse[]requiredThe month-by-month discount, by month_number.
Show schedule schema
amountstring | nullrequiredFor flat rows: dollars off that month.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show amount schema
string | nullFor flat rows: dollars off that month.
Variant 1: string
stringVariant 2: null
nulldiscount_typestringrequiredpercentage, flat or none.
month_numberintegerrequired1 is the billing period the promotion starts in.
percentagestring | nullrequiredFor percentage rows.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show percentage schema
string | nullFor percentage rows.
Variant 1: string
stringVariant 2: null
nullstackablebooleanrequiredWhether this promotion may combine with another on the same lease.
updated_atstringrequiredWhen the promotion last changed.
Format: date-time
valid_fromstring | nullrequiredFirst date it may be applied.
Format: date
Show valid_from schema
string | nullFirst date it may be applied.
Variant 1: string
stringVariant 2: null
nullvalid_untilstring | nullrequiredLast date it may be applied. Null means it does not expire.
Format: date
Show valid_until schema
string | nullLast date it may be applied. Null means it does not expire.
Variant 1: string
stringVariant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired