Understand the customer and property data model — billing entities, multi-property support, and billing-only customers.

Customers & Properties

NextRoute separates customers (billing entities) from properties (service locations). This separation is fundamental to how the platform handles billing, scheduling, and multi-location support.

Customer

A customer represents the person or business that pays for service. The customer record holds:

Field	Description
`name`	Full name (or `first_name` + `last_name`)
`email`	Used for invoices, notifications, and portal login
`phone`	Contact number
`billing_status`	`active`, `paused`, `canceled`, or `pending`
`stripe_customer_id`	Linked Stripe customer for payment processing
`promo_code_id`	Applied promotional discount
`referral_code`	Unique code for the referral program
`notes`	Internal notes visible to dispatchers
`custom_fields_json`	Flexible key-value data for your vertical

Billing Status

Status	Meaning
`pending`	Newly created, not yet active
`active`	Receiving service and being billed
`paused`	Temporarily suspended (e.g., vacation)
`canceled`	No longer a customer

Property

A property is a physical service location. Each property belongs to exactly one customer and holds:

Field	Description
`address`	Street address (auto-geocoded to lat/lng)
`service_plan_id`	Which plan governs frequency and pricing
`service_zone_id`	Which zone determines the route template
`bin_count`	Number of bins/units at this location
`bin_size`	Size descriptor (e.g., "64gal", "96gal")
`bin_location`	Where to find bins (e.g., "Side of house", "Driveway")
`trash_day`	Day of the week for trash pickup (per-property or uniform)
`trash_pickup_time`	Time trash is collected
`is_active`	Whether this property is currently serviced

Multi-Property Support

A single customer can have multiple properties. Common scenarios:

Property management company — one billing entity, dozens of rental addresses
Residential + vacation home — same customer, two service locations
Commercial client — multiple office or retail locations

Each property can have its own:

Service plan (different frequency or pricing)
Service zone (different route)
Bin configuration

Invoices roll up all properties under one customer, with per-property line items.

Billing-Only Customer

A billing-only customer is a customer record with no address of its own — the address lives on the property records. This is useful for:

Holding companies that pay for multiple locations
Property managers who are not at any service address
Corporate accounts

When creating a billing-only customer, simply omit the address on the customer and add addresses at the property level.

How Customers Connect to Routes

Customer
└── Property (has address, zone, plan)
    └── Route Template Stop (on a master route in that zone)
        └── Daily Route Stop (generated based on frequency)

When a customer is created with an address, zone, and plan:

A property is auto-created with the address and plan
If auto_add_to_route is enabled, a template stop is added to the zone's master route
The template stop's approval_status is set to approved (or pending if manual approval is required)
When daily routes are generated, the stop appears on the appropriate dates based on frequency

Customer Lifecycle

Creating a Customer

When you create a customer via the dashboard or API:

The address is auto-geocoded to lat/lng coordinates via Mapbox
A Stripe customer is created on your connected account (if Stripe is configured)
A welcome email is sent (if notification templates are configured)
The customer is added to the appropriate master route template

Soft delete: Sets deleted_at timestamp. Customer disappears from lists but data is preserved. Can be restored.
GDPR delete: Anonymizes PII (name becomes "Deleted User", email/phone/address cleared). Financial records (invoices, payments) are preserved for compliance.

Service Zones — how zones determine route assignment
Service Plans — frequency and pricing models
Invoices — per-property billing line items

Customers & Properties

On this page