Documentation

Rate Scripts

Table of Contents

Overview

Rate Scripts allow you to dynamically calculate pricing for reservations and requests in QReserve. By attaching a Rate Script to a rate, you can implement custom pricing logic based on various factors such as reservation details, user information, and more.

Context Variables

Rate Scripts have access to the following context variables:

reservation

Contains details about the current reservation being processed.

script

Information about the script's execution context:

  • attached_to_reservable_id: ID of the reservable this script is attached to
  • attached_to_named_unit_id: ID of the named unit (if applicable)
  • rate: Dictionary containing rate information
  • site_reservation_script_id: ID of the site reservation script

user_logged_in

Information about the authenticated user:

  • bot: Boolean indicating if the user is an admin bot
  • display_name: User's display name
  • email: User's email address
  • is_administrator: Boolean indicating if the user is an administrator
  • is_moderator: Boolean indicating if the user is a moderator
  • user_id: unique identifier for the user

Output Format

A Rate Script must return a dictionary with the following structure:

Field Type Required Description
rate number No The calculated rate amount
rate_int integer No Integer representation of the rate (in cents)
rate_unit string Yes Unit of measurement for the rate
rate_basis string Yes Basis for calculating the rate
rate_description string No Description of the rate
tax_rate integer No Tax rate to apply stored as 10000 * rate (e.g. 13.4% stored as 134000)
tax_code string No Tax code for the rate
tax_note string No Additional tax information
prorate_half_interval_multiplier number No Multiplier for half-interval proration
sku string No Stock Keeping Unit identifier
meta_data dict No Additional metadata for the rate

Note

Tax rates are stored as 10000 * rate where rate is the percentage rate of a tax rate. For example, a tax rate of 13.4% is stored as 10000 * 13.4 = 134000.

Valid rate_unit Values

  • per hour
  • per use
  • per block
  • each
  • per request
  • per session
  • per sample
  • per km
  • per mile
  • per mL
  • per L
  • per person
  • per day
  • per week
  • per month

Valid rate_basis Values

  • per unit
  • per reservable

Examples

Basic Rate Script

This simple script returns a fixed rate of $50 per hour:

# Basic Rate Script with fixed pricing
def compute_rate():
    return {
        'rate': 50.00,
        'rate_unit': 'per hour',
        'rate_basis': 'per unit',
        'rate_description': 'Standard hourly rate'
    }

# Return the computed rate
return compute_rate()

Dynamic Rate Based on User Type

This script applies different rates based on whether the user is an administrator:

# Apply different rates based on user type
is_admin = user_logged_in['is_administrator']

if is_admin:
    # Administrator discount
    return {
        'rate': 40.00,
        'rate_unit': 'per hour',
        'rate_basis': 'per unit',
        'rate_description': 'Admin discounted rate',
        'tax_rate': 50000,  # 5%
        'tax_code': 'ADMIN-5'
    }
else:
    # Regular user rate
    return {
        'rate': 60.00,
        'rate_unit': 'per hour',
        'rate_basis': 'per unit',
        'rate_description': 'Standard user rate',
        'tax_rate': 84000,  # 8.4%
        'tax_code': 'STD-8'
    }

Time-Based Pricing

This script implements different pricing tiers based on reservation duration:

# Implement tiered pricing based on reservation duration
reservation_hours = reservation['duration'] / 3600

# Define tier thresholds
if reservation_hours <= 2:
    # Short reservation (up to 2 hours)
    hourly_rate = 75.00
    description = 'Short-term rate'
if reservation_hours > 2 and reservation_hours <= 6:
    # Medium reservation (2-6 hours)
    hourly_rate = 60.00
    description = 'Medium-term rate'
if reservation_hours > 6:
    # Long reservation (over 6 hours)
    hourly_rate = 45.00
    description = 'Long-term rate'

return {
    'rate': hourly_rate,
    'rate_unit': 'per hour',
    'rate_basis': 'per unit',
    'rate_description': description,
    'sku': 'HOURLY-' + str(int(hourly_rate))
}

Volume Discount Pricing

This script implements a discount for higher volume usage:

# Apply volume discounts
requested_quantity = reservation['units']
base_rate = 25.00

# Calculate discount percentage based on quantity
if requested_quantity >= 20:
    discount = 0.25  # 25% discount
if requested_quantity < 20 and requested_quantity >= 10:
    discount = 0.15  # 15% discount
if requested_quantity < 10 and requested_quantity >= 5:
    discount = 0.10  # 10% discount
if requested_quantity < 5:
    discount = 0.00  # No discount

# Apply discount to base rate
discounted_rate = base_rate * (1 - discount)

return {
    'rate': discounted_rate,
    'rate_int': int(discounted_rate * 100),  # Store in cents as integer
    'rate_unit': 'per use',
    'rate_basis': 'per unit',
    'rate_description': str(int(discount*100)) + "% volume discount applied",
}

Best Practices

  1. Error Handling: Include error handling in your scripts to gracefully handle unexpected inputs.
  2. Code Comments: Document your rate calculation logic clearly with comments.
  3. Testing: Test your rate scripts with various scenarios before deploying.
  4. Default Values: Always provide sensible default values for optional fields.
  5. Performance: Keep scripts efficient, especially if they will be executed frequently.
  6. Consistency: Maintain consistent pricing logic across related resources.
  7. Documentation: Document any special pricing rules for administrators and users.