GrowFlow Booking SDK (Python)

Python SDK for the GrowFlow Booking API. Provides an async client for managing bookings, availability, customers, and quotas.

Installation

pip install growflow-booking-client

Quick Start

import asyncio
from growflow_booking import GrowFlowBookingClient

async def main():
    async with GrowFlowBookingClient(api_key="bk_live_xxx") as client:
        # Get available slots
        slots = await client.get_available_slots(
            tenant_slug="my-business",
            date="2024-03-15",
            service_id="service-uuid-here",
        )

        # Find an available slot
        available = [s for s in slots.slots if s.available]
        if available:
            # Create a booking
            result = await client.create_simple_booking(
                tenant_slug="my-business",
                service_id="service-uuid-here",
                date="2024-03-15",
                slot=available[0].time,
                customer_name="Mario Rossi",
                customer_email="mario@example.com",
            )

            if result.success:
                print(f"Booking created! Code: {result.booking.booking_code}")

asyncio.run(main())

Configuration

Environment Variables

export GROWFLOW_BOOKING_API_KEY="bk_live_xxx"
export GROWFLOW_BOOKING_URL="https://booking.growflow.studio/api/v1"  # optional

Direct Configuration

client = GrowFlowBookingClient(
    api_key="bk_live_xxx",
    base_url="https://booking.growflow.studio/api/v1",
    timeout=30.0,
    max_retries=3,
)

API Reference

Tenants

# Get public tenant info (for widget)
tenant = await client.get_tenant_public("my-business")

# Get tenant services
services = await client.get_tenant_services("my-business")

# Get full tenant details (authenticated)
tenant = await client.get_tenant_detail("my-business")

Availability

# Get available dates in a range
dates = await client.get_available_dates(
    tenant_slug="my-business",
    start_date="2024-03-01",
    end_date="2024-03-31",
    service_id="service-uuid",  # optional
)

# Get available time slots for a date
slots = await client.get_available_slots(
    tenant_slug="my-business",
    date="2024-03-15",
    service_id="service-uuid",
)

Bookings

# Create a simple booking
result = await client.create_simple_booking(
    tenant_slug="my-business",
    service_id="service-uuid",
    date="2024-03-15",
    slot="10:00",
    customer_name="Mario Rossi",
    customer_email="mario@example.com",
    customer_phone="+39123456789",  # optional
    notes="Special request",  # optional
)

# Create an experience booking
result = await client.create_experience_booking(
    tenant_slug="my-business",
    experience_type_id="experience-uuid",
    date="2024-03-15",
    slot="14:00",
    participants=4,
    customer_name="Mario Rossi",
    customer_email="mario@example.com",
)

# Get booking by ID (with email verification)
booking = await client.get_booking(booking_id="uuid", email="mario@example.com")

# List bookings (authenticated)
bookings = await client.list_bookings(
    date_from="2024-03-01",
    date_to="2024-03-31",
    status="confirmed",
)

# Update booking status
booking = await client.update_booking_status(
    booking_id="uuid",
    status="completed",
)

# Cancel booking
await client.cancel_booking(booking_id="uuid", reason="Customer request")

Customers

# List customers
customers = await client.list_customers(search="mario")

# Create customer
customer = await client.create_customer(
    name="Mario Rossi",
    email="mario@example.com",
    phone="+39123456789",
)

# Update customer
customer = await client.update_customer(
    customer_id="uuid",
    phone="+39987654321",
)

Quotas (for external integrations like SweatMate)

# Create quota for a customer
quota = await client.create_quota(
    customer_external_id="user_123",
    total_credits=10,
    source="sweatmate",
    source_reference="subscription_abc",
)

# Get customer credits
credits = await client.get_customer_credits("user_123")
print(f"Remaining: {credits.remaining_credits}")

# Use quota credit
usage = await client.use_quota(
    quota_id="quota-uuid",
    credits=1,
    booking_id="booking-uuid",
)

Error Handling

from growflow_booking import (
    GrowFlowBookingError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    QuotaExhaustedError,
)

try:
    result = await client.create_simple_booking(...)
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Tenant or service not found")
except ValidationError as e:
    print(f"Invalid data: {e.message}")
except QuotaExhaustedError:
    print("No credits remaining")
except GrowFlowBookingError as e:
    print(f"API error: {e}")

License

MIT