Resident benefit packages

Set an enrollment's price override

Sets or clears a per-tenant monthly price on one enrollment. Requires the resident_benefit_packages:write permission.

PUT

https://services.magicdoor.com/productexperiences/company-portal/resident-benefit-packages/enrollments/{enrollmentId}/retail-price-override

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

enrollmentIdstringrequired

The enrollment, as a Snowflake id in decimal string form.

example: 1842102338792357888

Body

application/json

customRetailPricenumber

The monthly amount to charge this tenant instead of the package price. Cannot be negative; 0 means the property manager is funding the package. Leave it out or send null to clear the override and go back to the normal price.

Response

200 · The enrollment, with `customRetailPrice` and `effectiveRetailPrice` updated.

idstringrequired

The enrollment, as a Snowflake id in decimal string form.

leaseIdstringrequired

The lease the enrolled tenant is on.

unitIdstringrequired

The unit that lease is for.

propertyIdstringrequired

The property that unit belongs to.

tenantIdstringrequired

The enrolled tenant.

packageIdstringrequired

The package the tenant is enrolled in.

statusenum<string>required

pendingActivation is enrolled but not yet live with the partner, active is live, cancelled is terminal — re-enrolling creates a new record.

pendingActivationactivecancelled

enrolledAtstring · date-timerequired

When the enrollment was created, in the company's timezone.

enrolledByenum<string>required

Who performed the enrollment. Always propertyManager for an enrollment made through this API.

tenantpropertyManagersystem

enrolledViastringrequired

The surface the enrollment came from. Enrollments made through this API are stamped company_portal.

commitmentMonthsintegerrequired

The commitment the tenant took on, copied from the package at enrollment and fixed afterwards.

committedUntilstring · date-timerequired

The end of the tenant's commitment, in the company's timezone. It is the floor for a tenant-requested cancellation, not for a property manager's.

serviceStartsAtstring · date-timerequired

When benefits and billing begin. Enrolling on or after the 15th of a month pushes this to the start of the next month; enrolling before a lease starts anchors it to the lease start.

retailPriceSnapshotnumberrequired

The package's list price at the moment of enrollment, as a decimal amount.

customRetailPricenumber

A per-tenant price the property manager set on this enrollment. Absent when there is none; 0 means the property manager funds it.

effectiveRetailPricenumberrequired

What this enrollment bills next: the per-tenant override if one is set, otherwise the price snapshot while the price lock holds, otherwise the package's current list price.

cancellationRequestedAtstring · date-time

When the tenant asked to cancel. Absent when no request is outstanding.

cancelAtstring · date-time

When a scheduled cancellation takes effect. Absent when nothing is scheduled. No charge is posted for a period starting on or after it.

cancelOriginenum<string>

Who scheduled the pending cancellation. Absent when nothing is scheduled.

tenantpropertyManagersystem

cancelledAtstring · date-time

When the enrollment actually reached cancelled. Absent until then.

cancelledByenum<string>

Who cancelled it. Absent until it is cancelled.

tenantpropertyManagersystem

cancelledReasonstring

The reason recorded with the cancellation. Absent until it is cancelled.

firstChargedAtstring · date-time

When the first charge posted. Absent until then.

paidThroughstring · date-time

Exclusive end of the latest month a charge actually posted for. Absent until the first charge. It is what paid-through cancellation maths is based on.

nextChargeDatestring · date-time

When the next monthly charge is due. Absent once the enrollment is cancelled.

400 · `customRetailPrice` is negative, or the enrollment is already cancelled.

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.

404 · No enrollment with that id on this company.

An override always beats both the price snapshot and the package's list price while it is set. It takes effect at the enrollment's next charge and never reprices a charge that has already posted. What MagicDoor charges the property manager does not change — the discount comes out of the property manager's margin.