/v1/facilities/{facility_id}/billing-runAuthentication
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>/billing-run' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"billing_date": "2026-10-29",
"dry_run": false,
"lease_ids": [
"00000000-0000-4000-8000-000000000001"
],
"override_soft_closed": false
}'Parameters
facility_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
billing_datestring | nullFormat: date
Show billing_date schema
string | nullVariant 1: string
stringVariant 2: null
nulldry_runbooleanDefault: false
lease_idsstring[] | nullShow lease_ids schema
string[] | nullVariant 1: string[]
string[]Variant 2: null
nulloverride_soft_closedbooleanDefault: false
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"commit_result": {
"errors": [
{
"code": "string",
"lease_id": "00000000-0000-4000-8000-000000000001",
"message": "string"
}
],
"event_count": 0,
"facility_id": "00000000-0000-4000-8000-000000000001",
"posted_entry_count": 0,
"skipped_entry_count": 0
},
"plan": {
"effective_date": "2026-10-29",
"facility_id": "00000000-0000-4000-8000-000000000001",
"facility_period": [
"string",
"string"
],
"lease_plans": [
{
"applied_rate_schedule_ids": [
"00000000-0000-4000-8000-000000000001"
],
"billing_period": [
"string",
"string"
],
"errors": [
{}
],
"is_first_period": false,
"lease_id": "00000000-0000-4000-8000-000000000001",
"lease_number": "string",
"new_billing_event_count": 0,
"new_entries": [
{
"amount": "<VALUE_MATCHING_PATTERN>",
"description": "string",
"discount_amount": "<VALUE_MATCHING_PATTERN>",
"due_date": "2026-10-29",
"effective_date": "2026-10-29",
"entry_type": "string",
"id": "00000000-0000-4000-8000-000000000001",
"idempotency_key": "string",
"invoice_number": "string",
"period_end": "2026-10-29",
"period_start": "2026-10-29",
"reference_id": "00000000-0000-4000-8000-000000000001",
"reference_type": "string",
"subtotal": "<VALUE_MATCHING_PATTERN>",
"tax_amount": "<VALUE_MATCHING_PATTERN>"
}
],
"new_next_billing_date": "2026-10-29",
"new_rate": "<VALUE_MATCHING_PATTERN>",
"planned_actions": [
{
"effective_on": "2026-10-29",
"kind": "string",
"reason": "string",
"target_id": "00000000-0000-4000-8000-000000000001"
}
]
}
],
"period_close_transitions": [
{}
],
"plan_errors": [
{}
]
}
},
"meta": {
"request_id": "string"
}
}application/json
dataBillingRunResponserequiredShow data schema
commit_resultFacilityCommitResultResponse | nullrequiredShow commit_result schema
FacilityCommitResultResponse | nullVariant 1: FacilityCommitResultResponse
errorsLeaseCommitErrorResponse[]requiredShow errors schema
codestringrequiredlease_idstringrequiredFormat: uuid
messagestringrequiredevent_countintegerrequiredfacility_idstringrequiredFormat: uuid
posted_entry_countintegerrequiredskipped_entry_countintegerrequiredVariant 2: null
nullplanFacilityBillingPlanResponserequiredShow plan schema
effective_datestringrequiredFormat: date
facility_idstringrequiredFormat: uuid
facility_periodobject[]requiredMin items: 2 · Max items: 2
lease_plansLeasePlanResponse[]requiredShow lease_plans schema
applied_rate_schedule_idsstring[]requiredShow applied_rate_schedule_ids schema
stringbilling_periodobject[]requiredMin items: 2 · Max items: 2
errorsobject[]requiredShow errors schema
objectis_first_periodbooleanrequiredlease_idstringrequiredFormat: uuid
lease_numberstringrequirednew_billing_event_countintegerrequirednew_entriesLedgerEntryInPlan[]requiredShow new_entries schema
amountstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
descriptionstringrequireddiscount_amountstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
due_datestring | nullrequiredFormat: date
effective_datestringrequiredFormat: date
entry_typestringrequiredidstring | nullrequiredFormat: uuid
idempotency_keystringrequiredinvoice_numberstring | nullrequiredperiod_endstring | nullrequiredFormat: date
period_startstring | nullrequiredFormat: date
reference_idstring | nullrequiredFormat: uuid
reference_typestring | nullrequiredsubtotalstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tax_amountstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
new_next_billing_datestringrequiredFormat: date
new_ratestring | nullrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show new_rate schema
string | nullVariant 1: string
Variant 2: null
planned_actionsPlannedActionResponse[]Decisions this run applies at commit. A dry run reports them and writes nothing.
Show planned_actions schema
effective_onstring | nullrequiredFor end_lease_promotion, the attachment's new ended_on.
Format: date
kindstringrequiredend_lease_promotion or hold_rate_schedule.
reasonstring | nullrequiredWhy billing decided it, e.g. schedule_exhausted.
target_idstringrequiredThe lease promotion or rate schedule the action applies to.
Format: uuid
period_close_transitionsobject[]requiredShow period_close_transitions schema
objectplan_errorsobject[]requiredShow plan_errors schema
objectmetaMetarequiredEnvelope 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