--- title: "Create a lease charge" method: POST path: "/leases/{lease_id}/charges" tags: ["Leases"] --- # Create a lease charge `POST /leases/{lease_id}/charges` ## Request - Base URL: `https://api.faireplace.com/api` - URL: `https://api.faireplace.com/api/leases/{lease_id}/charges` - Auth: HTTP bearer Create a new lease charge for a lease. **Validations performed:** - service_place / lease compatibility: The service must be attached to the same place as the lease's estate - Automatic resolution of the distribution key: If `distribution_key_id` is not provided, uses `default_distribution_key_id` from the `service_place` - Distribution / billing consistency: Checks that the distribution is compatible with the billing method (e.g., `CONSOMMATION_MESUREE` requires `RELEVE_DIRECT` or `PROVISION`) - Method / basis consistency: Checks that the billing method is compatible with the calculation basis - Lease type compatibility: Checks that the category and billing method are allowed for this lease type - Period validation: Checks that billing periods are within the lease boundaries and respect `max_provisional_months` if applicable - Category x basis compatibility: Checks that personnel calculation bases are only used with the EMPLOYEE category ## Path parameters - `lease_id` string, uuid, required ## Request body - CreateLeaseCharge: Data for creating a rental charge. **Validation rules:** - If `service_place_id` is provided, the service must be attached to the same place as the lease's estate and must be chargeable - If `distribution_key_id` is not provided, it will be automatically resolved from `service_place.default_distribution_key_id` (required if `service_place_id` is provided) - The distribution key allocation must be compatible with `calculation_method` (e.g.: `CONSOMMATION_MESUREE` requires `RELEVE_DIRECT` or `PROVISION`) - `calculation_method` and `calculation_basis` must be compatible (e.g.: `FORFAIT` requires `FORFAIT` as basis) - The category (via `category_id` or `service_place.category_id`) must be allowed for the lease type - If `calculation_method` is `PROVISION`, the period duration must not exceed `max_provisional_months` of the lease type - Billing periods must be within the lease boundaries (between `lease.start_date` and `lease.end_date`) - If `category_id` corresponds to `EMPLOYEE`, `calculation_basis` must be `PERSONNEL_75_POURCENT`, `PERSONNEL_40_POURCENT` or `PERSONNEL_100_POURCENT` - `service_place_id` string, uuid, nullable: Place service ID. If provided: - The service must be attached to the same place as the lease's estate - The service must be chargeable (`is_chargeable = true`) - The service must have a `default_distribution_key_id` if `distribution_key_id` is not provided - `category_id` string, uuid, nullable: Category ID. If not provided, it will be resolved from `service_place.category_id` if `service_place_id` is provided. The category must be allowed for the lease type. - `calculation_method` 'FORFAIT' | 'PROVISION' | 'DEPENSE_REELLE' | 'RELEVE_DIRECT', required: Charge billing mode to the tenant (provision/fixed/actual expense). **Compatibility rules:** - `CONSOMMATION_MESUREE` (distribution) requires `RELEVE_DIRECT` or `PROVISION` - `FORFAIT` requires `FORFAIT` as calculation basis - `DEPENSE_REELLE` requires `DEPENSE_REELLE` or a staff basis as calculation basis - `PROVISION` can be used with all calculation bases - The mode must be allowed for the lease type (`allow_provisional`, `allow_fixed`) - `calculation_basis` 'DEPENSE_REELLE' | 'FORFAIT' | 'PERSONNEL_75_POURCENT' | 'PERSONNEL_40_POURCENT' | 'PERSONNEL_100_POURCENT', required: Base de calcul d'une charge récupérable (art. 23-1). Les trois valeurs `PERSONNEL_…` s'écrivent avec un underscore après `PERSONNEL`, exactement comme en base: c'est la même orthographe partout. - `amount` number, required: Charge amount - `billing_period_start` string, date, nullable: Billing period start date. Must be: - >= `lease.start_date` - <= `billing_period_end` if provided - <= `lease.end_date` if the lease has an end date - `billing_period_end` string, date, nullable: Billing period end date. Must be: - >= `billing_period_start` - <= `lease.end_date` if the lease has an end date - If `calculation_method` is `PROVISION`, the duration must not exceed `max_provisional_months` of the lease type - `distribution_key_id` string, uuid, nullable: Distribution key ID. If not provided: - Will be resolved from `service_place.default_distribution_key_id` if `service_place_id` is provided - Otherwise, an error will be returned - `notes` string, nullable: Notes - `energy_efficiency` CreateEnergyEfficiencyForCharge: Data for creating a new energy efficiency contribution when creating a charge - `baseline_consumption` number, required: Consumption before works - `target_savings_percentage` number, required: Targeted savings percentage (0-100) - `monthly_contribution_amount` number, required: Monthly contribution amount - `duration_months` integer, required: Contribution duration in months - `work_description` string, required: Description of the completed works - `work_cost` number, nullable: Cost of works - `energy_audit_reference` string, nullable: Energy audit reference - `start_date` string, date, required: Contribution start date - `notes` string, nullable: Notes - `insurance` CreateColocatationInsuranceForCharge: Data for creating a new co-tenancy insurance when creating a charge - `contract_number` string, required: Insurance contract number - `insurance_company` string, required: Insurance company - `annual_premium` number, required: Annual premium - `recoverable_amount` number, required: Amount recoverable from tenants (less than or equal to annual premium) - `coverage_details` string, required: Coverage details - `policy_start_date` string, date, required: Policy start date - `policy_end_date` string, date, required: Policy end date (must be after start date) - `deductible_amount` number, nullable: Deductible amount - `coverage_limits` object, nullable: Coverage limits (JSON) - `exclusions` string, nullable: Coverage exclusions - `notes` string, nullable: Notes ## Response `201` Charge created successfully - LeaseCharge: Rental charge - `id` string, uuid, required: Unique identifier of the charge - `lease_id` string, uuid, required: Lease ID - `service_place_id` string, uuid, nullable: Place service ID - `category_id` string, uuid, nullable: Charge category ID - `calculation_method` 'FORFAIT' | 'PROVISION' | 'DEPENSE_REELLE' | 'RELEVE_DIRECT', required: Charge billing mode to the tenant (provision/fixed/actual expense). **Compatibility rules:** - `CONSOMMATION_MESUREE` (distribution) requires `RELEVE_DIRECT` or `PROVISION` - `FORFAIT` requires `FORFAIT` as calculation basis - `DEPENSE_REELLE` requires `DEPENSE_REELLE` or a staff basis as calculation basis - `PROVISION` can be used with all calculation bases - The mode must be allowed for the lease type (`allow_provisional`, `allow_fixed`) - `calculation_basis` 'DEPENSE_REELLE' | 'FORFAIT' | 'PERSONNEL_75_POURCENT' | 'PERSONNEL_40_POURCENT' | 'PERSONNEL_100_POURCENT', required: Base de calcul d'une charge récupérable (art. 23-1). Les trois valeurs `PERSONNEL_…` s'écrivent avec un underscore après `PERSONNEL`, exactement comme en base: c'est la même orthographe partout. - `amount` number, required: Charge amount - `billing_period_start` string, date, nullable: Billing period start date - `billing_period_end` string, date, nullable: Billing period end date - `last_regularization_date` string, date, nullable: Last regularization date - `distribution_key_id` string, uuid, nullable: Distribution key ID - `notes` string, nullable: Notes about the charge - `created_at` string, date-time, required: Creation date - `updated_at` string, date-time, required: Last modification date - `energy_efficiency` EnergyEfficiencyContribution: Contribution for sharing energy savings (Energy Transition Act) - `id` string, uuid, required: Unique identifier - `lease_charge_id` string, uuid, required: Associated charge ID - `baseline_consumption` number, required: Consumption before works - `target_savings_percentage` number, required: Targeted savings percentage - `monthly_contribution_amount` number, required: Monthly contribution amount - `remaining_months` integer, required: Remaining duration in months - `work_description` string, required: Description of the completed works - `work_cost` number, nullable: Cost of works - `energy_audit_reference` string, nullable: Energy audit reference - `start_date` string, date, required: Contribution start date - `end_date` string, date, required: Contribution end date - `notes` string, nullable: Notes - `created_at` string, date-time, required: Creation date - `updated_at` string, date-time, required: Last modification date - `insurance` ColocatationInsurance: Insurance taken out by the landlord on behalf of co-tenants - `id` string, uuid, required: Unique identifier - `lease_charge_id` string, uuid, required: Associated charge ID - `contract_number` string, required: Insurance contract number - `insurance_company` string, required: Insurance company - `annual_premium` number, required: Annual premium - `recoverable_amount` number, required: Amount recoverable from tenants - `coverage_details` string, required: Coverage details - `policy_start_date` string, date, required: Policy start date - `policy_end_date` string, date, required: Policy end date - `deductible_amount` number, nullable: Deductible amount - `coverage_limits` object, nullable: Coverage limits (JSON) - `exclusions` string, nullable: Coverage exclusions - `notes` string, nullable: Notes - `created_at` string, date-time, required: Creation date - `updated_at` string, date-time, required: Last modification date ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - `404`: Not found - `422`: Unprocessable Entity - `500`: Internal Server Error --- [API](https://skmtc.dev/faireplace/apis/faireplace-property-management-api.md) · [All operations](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/revisions/69de39762919?raw)