/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 GET \
--url 'https://api.staging.facily.ai/v1/promotions/<PROMOTION_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
promotion_idpath · stringrequiredFormat: uuid
Responses
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