/v1/promotions/{promotion_id}Authentication
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 PATCH \
--url 'https://api.staging.facily.ai/v1/promotions/<PROMOTION_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"applicability_rules": {},
"applicable_unit_group_ids": [
"00000000-0000-4000-8000-000000000001"
],
"auto_apply": false,
"channel_ids": [
"00000000-0000-4000-8000-000000000001"
],
"code": "string",
"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": false,
"max_uses": 1
}'Parameters
promotion_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[] | nullShow applicable_unit_group_ids schema
string[] | nullVariant 1: string[]
string[]Variant 2: null
nullauto_applyboolean | nullShow auto_apply schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullchannel_idsstring[] | nullShow channel_ids schema
string[] | nullVariant 1: string[]
string[]Variant 2: null
nullcodestring | nullMin length: 1 · Max length: 50
Show code schema
string | nullVariant 1: string
stringVariant 2: null
nulldescriptionstring | 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_onlyboolean | nullShow existing_tenant_only schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullfacility_idsstring[] | nullShow facility_ids schema
string[] | nullVariant 1: string[]
string[]Variant 2: null
nullhide_from_websiteboolean | nullShow hide_from_website schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullis_activeboolean | nullShow is_active schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullmax_usesinteger | nullMinimum: 1
Show max_uses schema
integer | nullVariant 1: integer
integerVariant 2: null
nullmin_available_unitsinteger | nullMinimum: 1 · Maximum: 1000
Show min_available_units schema
integer | nullVariant 1: integer
integerVariant 2: null
nullmin_stay_monthsinteger | nullMinimum: 1 · Maximum: 120
Show min_stay_months schema
integer | nullVariant 1: integer
integerVariant 2: null
nullmove_in_onlyboolean | nullShow move_in_only schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullnamestring | nullMin length: 1 · Max length: 100
Show name schema
string | nullVariant 1: string
stringVariant 2: null
nullprepay_monthsinteger | nullMinimum: 1 · Maximum: 36
Show prepay_months schema
integer | nullVariant 1: integer
integerVariant 2: null
nullprepay_requiredboolean | nullShow prepay_required schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullpriorityinteger | nullMinimum: 0 · Maximum: 10000
Show priority schema
integer | nullVariant 1: integer
integerVariant 2: null
nullrepeat_last_monthboolean | nullShow repeat_last_month schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullscheduleScheduleRowRequest[] | 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
nullstackableboolean | nullShow stackable schema
boolean | nullVariant 1: boolean
booleanVariant 2: null
nullvalid_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