Resident benefit packages

Update the resident benefit settings

Switches the program on or off, points the money at chart of accounts, and replaces the company's package list in one call. Requires the resident_benefit_packages:write permission.

PATCH

https://services.magicdoor.com/productexperiences/company-portal/resident-benefit-packages/settings

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.

Body

application/json

The settings fields are optional and only the ones you send are changed. packages is not — it is always the complete list you want to end up with.

enrolledInProgramboolean

Switch the program on or off. Switching it off cancels every live enrollment, so it needs confirmCancelActiveEnrollments. Switching it back on clears cancellations that the previous switch-off had scheduled.

recurringLeaseChargeChartOfAccountIdstring

The chart of account the tenant's monthly benefit charge is posted to, as a decimal string. Must be a revenue or other-revenue account on this company.

companyExpenseChartOfAccountIdstring

The chart of account MagicDoor's monthly charge to the property manager is posted to, as a decimal string. Must be an expense or other-expense account on this company.

lockRetailPriceDuringCommitmentboolean

Whether an enrollment keeps its sold price for the length of its commitment when the list price changes.

packagesobject[]required

The complete package list. Each item must be complete in itself — this endpoint does not merge partial packages. A stored package you leave out of the list is disabled, not deleted; use the delete endpoint to remove one.

confirmCancelActiveEnrollmentsboolean

Set it to true to go ahead with switching the program off when that would cancel live enrollments. Without it the call changes nothing and comes back asking for confirmation.

Response

200 · Either the updated settings, or a request to confirm cancelling live enrollments.

settingsobject

The settings after the change. Absent when confirmation is required, because nothing was changed.

requiresEnrollmentCancellationConfirmationbooleanrequired

true when switching the program off would end live enrollments and the request did not confirm it. Nothing was changed.

activeEnrollmentCountintegerrequired

How many live enrollments the confirmation would cancel. 0 when no confirmation is required.

packagesWithCostIncreaseWarningstring[]required

Ids of packages that gained a bundle while residents were enrolled, so MagicDoor's monthly cost for them goes up.

400 · A package rule was broken: a duplicate package id, a package that is not this company's, a missing name, no bundles, a duplicate or unknown bundle, a retired bundle being added, two bundles from the same provider or exclusivity group, a commitment under 3 months, a negative price, a bad custom line, or a chart of account of the wrong type.

401 · The request carried no valid access token.

403 · The caller is not a property manager, or is missing the `resident_benefit_packages:write` permission.

422 · A bundle was removed from a package that residents are still enrolled in.

Switching the program off

Switching the program off while tenants are enrolled ends those enrollments, so it takes two calls. Send the change without confirmCancelActiveEnrollments, and if it would cancel anything the response comes back with requiresEnrollmentCancellationConfirmation set to true, activeEnrollmentCount telling you how many, and no settings object — nothing was changed. Show the count, then send the same body again with confirmCancelActiveEnrollments set to true.

Changing a package that tenants already hold

A bundle can never be taken out of a package while residents are enrolled in it — that is rejected. Adding one is allowed, and because it raises what MagicDoor charges for that package, the package's id comes back in packagesWithCostIncreaseWarning so you can tell the property manager.