Property charges

Record a property charge

Books a charge against the property and creates the transaction behind it on the bank account you name. Optionally narrows the charge to one of the property's units or leases.

POST

https://api.portal.magicdoor.com/company-app/properties/{propertyId}/bills

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

propertyIdstringrequired

Snowflake id of the property the charge belongs to.

example: 1830472847398404097

Body

application/json

amountnumberrequired

How much to charge. A decimal with at most two places, and it must be greater than zero.

bankAccountIdstringrequired

The bank account the money lands in.

chartOfAccountIdstringrequired

The revenue account to book the amount to.

cashChartOfAccountIdstring

The cash asset account for the other side of the entry. Leave it out to use the bank account's own.

chargeDatestring · date

The date to book the charge against, as YYYY-MM-DD, read in the company's timezone. Leave it out to use today.

unitIdstring

Narrow the charge to one of the property's units.

leaseIdstring

Narrow the charge to one lease.

memostring

Free text, up to 200 characters.

externalTransactionIdstring

Your own reference for the payment, up to 100 characters, stored on the transaction so you can reconcile against your own system. It is not an idempotency key: sending the same value twice records two charges.

metadataobject

Your own key-value pairs to carry alongside the charge, as a map of strings to strings. Returned unchanged.

Response

200 · The new charge, with the property, portfolio and transaction it created expanded.

idstring

Snowflake id of the charge.

createdstring · date-time

When the charge was recorded, as a wall clock in the company's timezone with no offset.

updatedstring · date-time

When it last changed.

chargeDatestring · date

The date the charge is booked against, in the company's timezone.

amountnumber

How much, as a decimal amount such as 45.00. Always greater than zero.

memostring

Free text on the charge, up to 200 characters. Absent when none was written.

referencestring

A reference carried on the charge from the accounting side. Absent when there is none — no field on this API sets it.

chartOfAccountIdstring

The revenue account the amount was booked to.

transactionIdstring

The transaction this charge created. Read it from transactions on this same response to see the bank account and status.

portfolioIdstring

The portfolio behind the property. Derived, not supplied.

propertyIdstring

The property the charge is booked against.

unitIdstring

The unit the charge is narrowed to. Absent when the charge is against the whole property.

leaseIdstring

The lease the charge is narrowed to. Absent when it is not tied to one.

returnedTransactionIdstring

The transaction that pulled the money back. Absent unless the charge was returned.

returnedAmountnumber

How much came back. Absent unless the charge was returned.

returnedDatestring · date-time

When it came back. Absent unless the charge was returned.

returnedReasonstring

Why it came back. Absent unless the charge was returned.

filesobject[]

Documents attached to the charge. Empty in practice — this API has no endpoint that attaches one.

metadataobject

Whatever you passed as metadata when the charge was created, as a map of string keys to string values. Empty when none was given.

creatorobject

Who recorded the charge.

portfolioobject

The portfolio behind the property, expanded.

propertyobject

The property the charge is booked against, expanded.

unitobject

The unit the charge is narrowed to, expanded. Absent when the charge is against the whole property.

leaseLease

The lease the charge is narrowed to, in the same shape the leases endpoints return. Absent when it is not tied to one.

transactionsTransaction[]

The transaction this charge created, and the returning transaction if there is one, in the same shape the transactions endpoints return.

bankAccountsBankAccount[]

The bank accounts those transactions touch.

chartOfAccountsChartOfAccount[]

The ledger accounts those transactions touch.

creatorInfoobject

The record behind creator, expanded. Exactly one of the four is present, matching creator.type; all four are absent for system and magicDoor.

400 · A required field is missing, `amount` is zero or negative or has more than two decimal places, the memo is over 200 characters, or one of the ids is not a decimal number. The response carries an `errors` member mapping each rejected field name to its message.

401 · The access token is missing, expired, or not for this company.

404 · The property, bank account, ledger account, unit or lease does not exist or belongs to another company.

What a property charge is

A property charge is income a property earns outside the rent — laundry, vending, parking, amenity and service fees. It is booked against the property, and optionally against one of its units or leases, and it always produces a transaction on a bank account. Rent and other tenant charges are lease charges and live on the leases endpoints instead.

The same operation answers on two paths

This controller is registered on both /company-app/properties/{propertyId}/bills and /company-app/properties/{propertyId}/charges. Both paths reach the same code and behave identically. The pages here document the /bills form.