Rental Rates

A rental rate is the price you charge to rent a Product for one billing period. "Scissor Lift, 26 ft — $250/day" is a rental rate; the Product it points at is the equipment, and the rate is simply what it costs to keep that equipment out for a day, a week, or a month. Rates are the pricing layer that feeds rental agreements — when a rental is reserved or picked up, the system fills in the rate of any line that has none from the matching rate, rather than asking you to retype a price every time.

Rate vs. agreement, in one line: a rate is a reusable price-list entry for a Product; an agreement is one customer renting specific equipment for a date range. The agreement resolves a rate to know what to bill.

What a rental rate holds #

Each rate ties together a Product, a period, and a price, plus optional scoping:

• Product — the piece of equipment being priced. Required. Only Returnable equipment is rentable, so this points at a returnable Product.
• Period — Daily, Weekly, or Monthly (see below). Required.
• Rate — the price for one period, entered in dollars in the UI and stored in cents under the hood. Required.
• Minimum periods — recorded with the rate (defaults to 1). Billing does not use it yet: a rental is billed for the periods it ran, and at least one.
• Customer override — leave blank for the standard rate, or set it to give a specific customer negotiated pricing.
• Location override — scope the rate to a single inventory location, useful when the same Product rents for different prices by location.
• Active — only active rates are used when a line's rate is filled in, at reserve or pickup; switch one off to retire it without deleting it.

Per-period pricing #

Every rate is priced against exactly one period, and the period also decides how a calendar span converts into billable units:

• Daily — one period spans 1 day.
• Weekly — one period spans 7 days.
• Monthly — one period is a calendar month, counted from the rental's first day. Picked up on July 1, July 1 to July 31 is one month and August 1 starts the second. A rental that starts on the 29th, 30th or 31st starts each later month on that date, or on the last day of a shorter month: from January 31, the months start January 31, February 28 (29 in a leap year) and March 31.

A rental is billed enough whole periods to cover its days, counted over the whole rental, so it is billed the same periods whether it is invoiced on a billing cycle or once at close.

You can have several rates for the same Product at different periods — a daily, a weekly, and a monthly price — and the agreement picks the one matching the rental's chosen period. The period a rate is created with defaults to Daily.

Set complementary daily/weekly/monthly rates on a Product so longer rentals get a better effective price — e.g. $50/day, $250/week, $800/month — and let the agreement choose the period that fits the booking.

Prices are stored in cents #

Like every money field in Knowledge ERP, the rate is an integer number of cents in the database and over the API. 5000 means $50.00. The rate form shows and accepts dollars (with a $ prefix) and converts to cents on save, so you never type cents by hand in the UI — but if you script rates through the API, you send and receive whole cents.

How rates attach to Products #

A rate always belongs to one Product through its product_id. Because a Product can carry many rates — different periods, plus customer- and location-specific overrides — pricing for a piece of equipment is expressed as a small set of rate rows rather than a single number on the Product. Manage them under Rentals → Rental Rates, where the list shows the Product, period, price, any customer or location override, and whether the rate is active. The list sorts newest-first and you edit a rate in place.

How a rate is chosen (resolution) #

When a rental is priced, the system resolves the best matching active rate for the Product and period. More specific rates win:

1. A rate matching both the renting customer and the rental's location.
2. A rate matching the customer.
3. A rate matching the location.
4. The generic rate (no customer, no location) as the fallback.

Only rates flagged active are considered. When a line's rate is filled in, a rate set for another customer or another Location is not used, and a line whose rate was already filled in keeps it. If two active rates are equally specific, the one created most recently wins. The rate is found for the rental's customer and Location, whatever the person pressing Reserve is allowed to see.

Picking the most specific rate is what lets you publish a standard price for everyone, then quietly override it for a key account or a single location without touching the default. See equipment rentals for how resolved rates flow into a rental's charges.

When nothing matches #

If no active rate matches the Product and period — none was ever configured, the only one is switched off, or the line uses a period you never priced — the rental is refused rather than priced at nothing. Reserving, picking up and invoicing all stop with a message naming the product and the missing period.

You have two ways forward, and they mean different things:

• Add the rate here, then retry. This is the usual fix.
• Type a rate of 0 directly on the agreement line, if the rental really is free of charge. That is a decision the system records and respects — it will not be overwritten by a rate you add later.

What is never allowed is a line that nobody priced going out the door and coming back as a $0 invoice.

Editing and retiring rates #

Rates are versioned through the change tracker, so every edit to a price, period, or override is captured in the rate's change history. To stop using a rate, switch active off (it stays on the record and in history) or delete it — deleting soft-deletes the rate, and any rental agreements that already referenced it are unaffected.

Doing it from the API #

# List rental rates (filter by Product, period, or active status)
curl "https://your-domain.com/api/v1/rental-rates?period=day&active=1" \
  -H "Authorization: Bearer $TOKEN"

# Create a rental rate at $50.00/day
curl -X POST "https://your-domain.com/api/v1/rental-rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "...", "period": "day", "rate": 5000, "min_periods": 1}'

Over the API the rate is an integer in cents (5000 = $50.00), the period is one of day, week, or month, and relationships use _id field names — product_id, customer_id, location_id.