Subscriptions Overview

A subscription is a resident’s enrollment in a service that an outside provider offers through Fortress, such as rent reporting. This page is for partners who build an integration with resident subscriptions. It explains the fields, the filters, and the webhook events that you use to keep your records in step with Fortress.

Endpoints

Endpoint	Summary	Method
`/subscriptions`	List Subscriptions	GET
`/subscriptions/{subscriptionId}`	Read Subscription	GET

Fields

Provider and service

provider is the slug of the provider, for example PINATA.
serviceType is the type of service the provider offers, for example RENT_REPORTING.

Status

A subscription has one of these statuses.

PENDING: the resident enrolled and the subscription has not started.
ACTIVE: the subscription is in force.
PAST_DUE: the last payment for the subscription failed.
SUSPENDED: Fortress suspended the subscription.
ENDED: the subscription is over. A resident can enroll again after it ends.

Change reason

changeReason gives the reason for the last change to the subscription.

Value	When it occurs
`ENROLLMENT`	The resident enrolls.
`RESIDENT_UPGRADE`	The resident moves to a higher plan.
`RESIDENT_DOWNGRADE`	The resident moves to a lower plan.
`NONPAYMENT_SUSPENSION`	Fortress suspends the subscription because a payment failed.
`LEASE_RENEWAL`	The household renews its lease and the subscription moves to the new lease.
`MOVE_OUT`	A resident moves out and other residents stay.
`HOUSEHOLD_MOVE_OUT`	The last resident moves out, or a collections claim is created.
`PROPERTY_DISABLED`	Fortress disables the property.

Plan and price

planCode is the current plan. The provider defines the codes.
previousPlanCode is the plan before the last plan change. The provider defines the codes. It is null if the plan never changed.
priceCents is the plan price in cents. Fortress copies it from the provider at enrollment.

Other fields

partnerReference is the ID that the provider uses for the resident. It is null until the provider assigns one.
leaseId moves to the new lease on lease renewal.
version increases on every change to the subscription.

Soft-deleted subscriptions do not appear. Fortress does not return consent details or billing details.

Filtering

To list the active rows of one provider, filter on provider and status. For example, use provider = "PINATA" and status = "ACTIVE".

String fields filter by exact value. A filter on provider=pinata does not match PINATA.

Events

Fortress will send these events by webhook. They are defined, not yet delivered: build and test against the trigger. Route on eventType. For the three subscription.* events, act only on events whose provider is your own. customer.updated and lease.updated carry no provider: read each id in subscriptionIds through the subscriptions resource, and act when one of those rows carries your slug.

Event	Fires when
`subscription.created`	A resident subscription starts.
`subscription.updated`	A resident subscription changes plan or status.
`subscription.ended`	A resident subscription ends.
`customer.updated`	A customer with a live subscription changes a watched field.
`lease.updated`	The lease of a household with a live subscription changes a watched field.

Apply the events with these rules.

For subscription.updated, read planCode and changeReason to learn what changed.
When customer.updated or lease.updated names a changed field, read the current values from the customers and leases resources.
Order the events of one subscription by version.

Identity

customerId is the stable ID of a resident. It stays the same across leases, renewals, and transfers within one organization.

Rent status

Rent payment status comes from the transactions resource, not from the subscription. Fortress will document how to read a household’s rent status there in a later release.

Testing your receiver

Send POST /webhooks/trigger with eventType, organizationId, propertyId, and partnerKey. partnerKey is required for the subscription, customer, and lease events. Fortress sends the example payload of that event to the active webhook subscriptions of the property that are registered under partnerKey and list the event type, with "test": true in the signed body (and the header X-Fortress-Test-Event: true as a convenience copy) so your receiver can tell a sample from a real event. partnerKey is the lowercase key your subscriptions are registered under, not the provider slug. See Trigger a webhook event.

Polling

Pull the list once a day unless your integration needs fresher data. The rate limit of your API key is on the API overview page.