Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsTrigger Billing Run
Search the full API reference Esc to close

Trigger Billing Run

Billing · REST API reference

Get support
POST/v1/facilities/{facility_id}/billing-run

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>/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
}'
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

billing_datestring | null

Format: date

Show billing_date schema
string | null
Variant 1: string
string
Variant 2: null
null
dry_runboolean

Default: false

lease_idsstring[] | null
Show lease_ids schema
string[] | null
Variant 1: string[]
string[]
Variant 2: null
null
override_soft_closedboolean

Default: false

Responses

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

200Successful Response
JSON · generated example
{
  "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

dataBillingRunResponserequired
Show data schema
commit_resultFacilityCommitResultResponse | nullrequired
Show commit_result schema
FacilityCommitResultResponse | null
Variant 1: FacilityCommitResultResponse
errorsLeaseCommitErrorResponse[]required
Show errors schema
codestringrequired
lease_idstringrequired

Format: uuid

messagestringrequired
event_countintegerrequired
facility_idstringrequired

Format: uuid

posted_entry_countintegerrequired
skipped_entry_countintegerrequired
Variant 2: null
null
planFacilityBillingPlanResponserequired
Show plan schema
effective_datestringrequired

Format: date

facility_idstringrequired

Format: uuid

facility_periodobject[]required

Min items: 2 · Max items: 2

lease_plansLeasePlanResponse[]required
Show lease_plans schema
applied_rate_schedule_idsstring[]required
Show applied_rate_schedule_ids schema
string
billing_periodobject[]required

Min items: 2 · Max items: 2

errorsobject[]required
Show errors schema
object
is_first_periodbooleanrequired
lease_idstringrequired

Format: uuid

lease_numberstringrequired
new_billing_event_countintegerrequired
new_entriesLedgerEntryInPlan[]required
Show new_entries schema
amountstringrequired

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

descriptionstringrequired
discount_amountstringrequired

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

due_datestring | nullrequired

Format: date

effective_datestringrequired

Format: date

entry_typestringrequired
idstring | nullrequired

Format: uuid

idempotency_keystringrequired
invoice_numberstring | nullrequired
period_endstring | nullrequired

Format: date

period_startstring | nullrequired

Format: date

reference_idstring | nullrequired

Format: uuid

reference_typestring | nullrequired
subtotalstringrequired

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

tax_amountstringrequired

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

new_next_billing_datestringrequired

Format: date

new_ratestring | nullrequired

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

Show new_rate schema
string | null
Variant 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 | nullrequired

For end_lease_promotion, the attachment's new ended_on.

Format: date

kindstringrequired

end_lease_promotion or hold_rate_schedule.

reasonstring | nullrequired

Why billing decided it, e.g. schedule_exhausted.

target_idstringrequired

The lease promotion or rate schedule the action applies to.

Format: uuid

period_close_transitionsobject[]required
Show period_close_transitions schema
object
plan_errorsobject[]required
Show plan_errors schema
object
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
Continue exploringAll billing operations
Build something that works beautifully.

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

Trigger Billing Run | Facily Developers