Roller Data API - Python Client

Complete Python implementation for interacting with the Roller Data API.

📁 Project Files

roller-api-project/
├── .env.example              # Environment variables template
├── requirements.txt          # Python dependencies
├── roller_client.py          # Main API client
├── models.py                 # Data models for type safety
├── examples.py               # Usage examples
├── ROLLER_API_DOCUMENTATION.md  # Complete API documentation
└── README.md                 # This file

🚀 Quick Start

Step 1: Set Up Your Environment

# Navigate to project directory
cd roller-api-project

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Mac/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Credentials

1. Copy .env.example to .env:

   cp .env.example .env

2. Edit .env and add your Roller API credentials:

   ROLLER_CLIENT_ID=your_actual_client_id
   ROLLER_CLIENT_SECRET=your_actual_client_secret
   ROLLER_API_URL=https://api.roller.app
   

Step 3: Test the Connection

Create a simple test file test_connection.py:

from roller_client import RollerAPIClient

# Initialize client
client = RollerAPIClient()

# Test getting products
products = client.get_products(page_size=10, page_number=1)
print(f"Successfully connected! Found {products['totalItems']} products")

Run it:

python test_connection.py

📚 Usage Examples

Example 1: Get Bookings

from roller_client import RollerAPIClient

client = RollerAPIClient()

# Get bookings for a specific date range
bookings = client.get_bookings(
    start_date="2024-01-01",
    end_date="2024-01-31",
    page_size=500,
    page_number=1
)

print(f"Total bookings: {bookings['totalItems']}")

for booking in bookings['items']:
    print(f"Booking {booking['bookingReference']}: {booking['bookingStatus']}")

Example 2: Get All Products with Pagination

from roller_client import RollerAPIClient

client = RollerAPIClient()

# Get all products (automatic pagination)
all_products = client.get_all_pages('get_products')

print(f"Retrieved {len(all_products)} products")

# Filter published products
published = [p for p in all_products if p['productStatus'] == 'Published']
print(f"Published products: {len(published)}")

Example 3: Revenue Analysis

from roller_client import RollerAPIClient

client = RollerAPIClient()

# Get revenue data
revenues = client.get_revenues(
    start_date="2024-01-01",
    end_date="2024-01-31",
    page_number=1
)

# Calculate totals
total_revenue = sum(item['netRevenue'] for item in revenues['items'])
print(f"Total net revenue: ${total_revenue:,.2f}")

Example 4: Customer Information

from roller_client import RollerAPIClient
from models import Customer

client = RollerAPIClient()

# Get customers
customers_response = client.get_customers(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# Convert to model objects for better type safety
customers = [Customer.from_dict(item) for item in customers_response['items']]

for customer in customers:
    print(f"{customer.first_name} {customer.last_name} - {customer.email}")

🎯 Available API Methods

Core Data Endpoints

Method	Description
get_bookings()	Get booking items
get_tickets()	Get ticket information
get_payments()	Get payment details
get_customers()	Get customer data
get_products()	Get product catalog
get_staff()	Get staff information
get_attendance()	Get attendance records
get_revenues()	Get revenue data

Additional Endpoints

Method	Description
get_gxs_surveys()	Get GXS survey data
get_gift_cards()	Get gift card information
get_waivers()	Get waiver templates
get_signed_waivers()	Get signed waiver records
get_booking_signed_waivers()	Get booking-specific waivers
get_discounts()	Get discount information
get_locations()	Get venue locations
get_devices()	Get device information
get_reporting_categories()	Get revenue categories
get_till_reconciliations()	Get till reconciliation data
get_membership_redemptions()	Get membership redemptions
get_membership_statuses()	Get membership status changes
get_membership_credits()	Get membership credits

📊 Data Models

The models.py file provides Python dataclasses for type-safe data handling:

• BookingItem
• Product
• Customer
• Payment
• Staff
• Ticket
• GiftCard
• Waiver
• SignedWaiver
• Discount
• Location
• Device
• Attendance
• Revenue

Using Data Models

from roller_client import RollerAPIClient
from models import Product, Customer

client = RollerAPIClient()

# Get products and convert to model objects
products_response = client.get_products()
products = [Product.from_dict(item) for item in products_response['items']]

# Now you have type-safe access
for product in products:
    if product.cost:
        print(f"{product.name}: ${product.cost}")

🔧 Advanced Usage

Pagination Helper

The get_all_pages() method automatically handles pagination:

# Get ALL products across all pages
all_products = client.get_all_pages('get_products')

# Get ALL bookings for a date range
all_bookings = client.get_all_pages(
    'get_bookings',
    start_date='2024-01-01',
    end_date='2024-01-31'
)

Error Handling

from roller_client import RollerAPIClient

client = RollerAPIClient()

try:
    bookings = client.get_bookings(
        start_date="2024-01-01",
        end_date="2024-01-31"
    )
    print(f"Success! Got {bookings['totalItems']} bookings")
    
except Exception as e:
    print(f"Error: {e}")
    # Handle error appropriately

Custom Date Ranges

from datetime import datetime, timedelta

# Get yesterday's data
yesterday = (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d')
today = datetime.now().strftime('%Y-%m-%d')

bookings = client.get_bookings(
    start_date=yesterday,
    end_date=today
)

# Get last 7 days
week_ago = (datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d')
revenues = client.get_revenues(
    start_date=week_ago,
    end_date=today
)

📝 Common Patterns

Daily Reports

def generate_daily_report(client, date):
    """Generate a comprehensive daily report"""
    
    bookings = client.get_bookings(start_date=date, end_date=date)
    attendance = client.get_attendance(start_date=date, end_date=date)
    revenues = client.get_revenues(start_date=date, end_date=date)
    
    return {
        'total_bookings': bookings['totalItems'],
        'total_checkins': attendance['totalItems'],
        'total_revenue': sum(r['netRevenue'] for r in revenues['items'])
    }

# Usage
from datetime import datetime
today = datetime.now().strftime('%Y-%m-%d')
report = generate_daily_report(client, today)
print(report)

Product Catalog Export

import json

# Get all products
all_products = client.get_all_pages('get_products')

# Filter active products
active_products = [
    p for p in all_products 
    if p['productStatus'] == 'Published'
]

# Export to JSON
with open('products_catalog.json', 'w') as f:
    json.dump(active_products, f, indent=2)

Customer Analytics

# Get customers from last month
customers = client.get_customers(
    start_date='2024-01-01',
    end_date='2024-01-31'
)

# Analyze marketing opt-ins
total = len(customers['items'])
opted_in = sum(1 for c in customers['items'] if c['acceptMarketing'])

print(f"Marketing opt-in rate: {opted_in/total*100:.1f}%")

🐛 Troubleshooting

"Invalid credentials" error

• Check your .env file has correct ROLLER_CLIENT_ID and ROLLER_CLIENT_SECRET
• Verify credentials are active in your Roller account

"Token expired" error

• The client automatically refreshes tokens
• If this persists, check your system clock is correct

"Connection refused" error

• Check your internet connection
• Verify ROLLER_API_URL is correct in .env
• Check if Roller API is experiencing downtime

Import errors

• Make sure virtual environment is activated
• Run pip install -r requirements.txt again

📖 Further Documentation

• See ROLLER_API_DOCUMENTATION.md for complete API reference
• Run examples.py to see all usage examples in action
• Check models.py for all available data models

🤝 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Review the examples in examples.py
3. Consult Roller API documentation
4. Contact Roller support for API access issues

📄 License

This implementation is provided as-is for use with Roller API.

---

Happy coding! 🚀