Medusa Booking System Plugin

A comprehensive booking system plugin for MedusaJS that enables you to define resources, configure availability rules, set up pricing, and manage bookings through both admin and storefront interfaces.

Introduction

The Medusa Booking System Plugin extends your Medusa e-commerce platform with powerful booking capabilities. Whether you're managing hotel rooms, equipment rentals, appointment scheduling, or any time-based resource, this plugin provides the tools you need to:

• Define Resources: Create bookable resources with custom types and configurations
• Configure Availability: Set up flexible availability rules with priority-based scheduling
• Booking Rules: Define policy rules (payment, confirmation, reservation TTL) with global or per-resource scope
• Manage Pricing: Configure dynamic pricing based on dates, quantities, and custom rules
• Handle Bookings: Process bookings through carts, orders, and allocations
• Admin Dashboard: Manage all aspects of your booking system through an intuitive admin interface

Features

Core Capabilities

• Resource Management: Create and manage bookable resources with product integration
• Availability Rules: Define complex availability patterns with priority-based rule system
• Booking Rules: Policy rules for payment requirements, confirmation flow, reservation TTL, and custom config; scope can be global or per-resource with priority and validity windows
• Pricing Configuration: Set up flexible pricing models with multiple price points;
• Booking Workflows: Complete booking flow from cart to order creation
• Resource Allocations: Track and manage time-based resource allocations
• Status Management: Control resource visibility with draft/published status
• Admin Interface: Full-featured admin dashboard for managing bookings, resources, and booking rules

Resource Types

Resources can be configured with different types (e.g., "room", "equipment", "appointment") and support:

• Custom pricing units (hourly, daily, weekly, etc.)
• Bookable/non-bookable status
• Product integration for seamless e-commerce experience

Availability System

The availability system supports:

• Multiple availability rules per resource
• Priority-based rule evaluation
• Available/unavailable effects
• Date range validity
• Custom rule configurations
• Active/inactive rule states

Booking Rules (Policies)

Booking rules define policy behavior applied at evaluation time:

• Scope: global (all resources) or resource (specific resource IDs)
• Policy fields: require_payment, require_confirmation, reservation_ttl_seconds
• Optional: configuration (custom JSON), priority, valid_from / valid_until, is_active
• Resolution: Rules are merged by priority; store and admin can resolve effective rules for a given time (and optionally resource) via the rules endpoints.

Pricing System

Flexible pricing configuration:

• Multiple pricing configurations per resource
• Currency-based pricing
• Product variant integration

Installation

Prerequisites

• Node.js >= 20
• MedusaJS v2.7.0 or higher
• PostgreSQL database

Step 1: Add the Package

Add the booking system plugin to your Medusa application:

npm install @rsc-labs/medusa-booking-system

Or if using yarn:

yarn add @rsc-labs/medusa-booking-system

Step 2: Configure the Plugin

Add the plugin to your Medusa configuration. In your medusa-config.ts or medusa-config.js:

import { defineConfig } from "@medusajs/framework";

export default defineConfig({
  // ... your existing config
  plugins: [
    // ... your existing modules
    {
      resolve: "@rsc-labs/medusa-booking-system",
      options: {},
    },
  ],
});

Step 3: Generate Migrations

Generate the database migrations for the booking module:

npx medusa db:generate bookingModule

Step 4: Run Migrations

Apply the migrations to your database:

npx medusa db:migrate

API Reference

The plugin provides two sets of API endpoints:

Store APIs (Public)

Public-facing endpoints for customers to browse and book resources.

Booking Resources

• GET /store/booking-resources - List all available booking resources
• GET /store/booking-resources/[id] - Get a specific booking resource (optional query: region_id for region-based calculated pricing)
• GET /store/booking-resources/[id]/availability - Get availability information
• GET /store/booking-resources/[id]/rules - Get resolved booking rules for the resource (optional query: evaluation_time as ISO date string)
• POST /store/booking-resources/[id]/hold - Hold a resource for a time period

Booking Carts

• POST /store/booking-carts - Create a new booking cart
• GET /store/booking-carts/[id] - Get cart with booking line items
• POST /store/booking-carts/[id] - Update cart customer information
• POST /store/booking-carts/[id]/items - Add booking item to cart
• DELETE /store/booking-carts/[id]/items/[itemId] - Remove item from cart
• POST /store/booking-carts/[id]/complete - Complete booking cart (creates order)

Admin APIs (Authenticated)

Administrative endpoints for managing the booking system.

Booking Resources

• GET /admin/booking-resources - List all booking resources
• POST /admin/booking-resources - Create a new booking resource
• GET /admin/booking-resources/[id] - Get booking resource details
• POST /admin/booking-resources/[id] - Update booking resource
• DELETE /admin/booking-resources/[id] - Delete booking resource
• GET /admin/booking-resources/[id]/availability - Get availability for date range
• POST /admin/booking-resources/[id]/status - Update resource status (published/draft)

Booking Rules

• GET /admin/booking-rules - List all booking rules (with booking resources count)
• POST /admin/booking-rules - Create a booking rule
• GET /admin/booking-rules/[id] - Get a booking rule (with booking resources count)
• POST /admin/booking-rules/[id] - Update a booking rule
• DELETE /admin/booking-rules/[id] - Delete a booking rule
• GET /admin/booking-rules/evaluate - Evaluate resolved rules (query: evaluation_time required, optional booking_resource_id)

Availability Rules

• GET /admin/booking-resources/[id]/availability-rules - List availability rules
• POST /admin/booking-resources/[id]/availability-rules - Create availability rule
• GET /admin/booking-resources/[id]/availability-rules/[ruleId] - Get specific rule
• POST /admin/booking-resources/[id]/availability-rules/[ruleId] - Update rule
• DELETE /admin/booking-resources/[id]/availability-rules/[ruleId] - Delete rule

Pricing

• POST /admin/booking-resources/[id]/pricing - Create pricing configuration
• POST /admin/booking-resources/[id]/pricing/[priceConfigId] - Update pricing
• DELETE /admin/booking-resources/[id]/pricing/[priceConfigId] - Delete pricing

Bookings

• GET /admin/bookings - List all bookings
• POST /admin/bookings - Create a booking
• GET /admin/bookings/[id] - Get booking details
• POST /admin/bookings/[id]/cancel - Cancel a booking
• GET /admin/bookings/stats - Get booking statistics

For detailed API documentation including request/response schemas, see the Swagger/OpenAPI specification.

Admin UI (Booking)

The admin dashboard under Booking includes:

• Overview – Booking stats and recent activity
• Resources – List and manage booking resources; create, edit, view availability, pricing, and status
• Rules – List, create, edit, and delete booking rules; test rule evaluation for a given time and optional resource
• Bookings – List and manage bookings; create and cancel

Complete Scenario Walkthrough

This example demonstrates the complete flow from creating a resource to booking it on the storefront.

Step 1: Create a Booking Resource

Create a new bookable resource (e.g., a conference room):

curl -X POST http://localhost:9000/admin/booking-resources \
  -H "Content-Type: application/json" \
  -d '{
    "booking_resource": {
      "resource_type": "conference_room",
      "title": "Executive Conference Room",
      "subtitle": "Capacity: 20 people",
      "description": "A spacious conference room with AV equipment",
      "is_bookable": true,
      "pricing_unit": "hour",
      "pricing_unit_value": 1
    }
  }'

Response includes the created resource with an ID (e.g., br_01HXXX...).

Step 2: Create Availability Rules

Set up when the resource is available:

curl -X POST http://localhost:9000/admin/booking-resources/br_01HXXX.../availability-rules \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "weekly",
    "name": "Business Hours",
    "effect": "available",
    "priority": 1,
    "configuration": {
      "days": [1, 2, 3, 4, 5], // Monday to Friday
      "start_time": "09:00",
      "end_time": "17:00"
    },
    "is_active": true
  }'

Step 3: Create Pricing Configuration

Set up pricing for the resource:

curl -X POST http://localhost:9000/admin/booking-resources/br_01HXXX.../pricing \
  -H "Content-Type: application/json" \
  -d '{
    "booking_resource_pricing_config": {
      "name": "Standard Hourly Rate"
    },
    "booking_resource_pricing": [
      {
        "currency_code": "usd",
        "amount": 5000, // $50.00 per hour
        "min_quantity": 1,
        "max_quantity": 1
      }
    ]
  }'

Step 4: Publish the Resource

Make the resource available on the storefront:

curl -X POST http://localhost:9000/admin/booking-resources/br_01HXXX.../status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "published"
  }'

Step 5: Check Availability and Resource (Storefront)

Customers can fetch a resource with region-based pricing and check availability:

# Get resource with region-based calculated price
curl "http://localhost:9000/store/booking-resources/br_01HXXX...?region_id=reg_xxx"

# Check availability
curl "http://localhost:9000/store/booking-resources/br_01HXXX.../availability?startDate=2026-02-15&endDate=2026-02-20"

# Optional: get resolved booking rules for the resource
curl "http://localhost:9000/store/booking-resources/br_01HXXX.../rules?evaluation_time=2026-02-15T10:00:00Z"

Step 6: Create Booking Cart (Storefront)

Customer creates a booking cart:

curl -X POST http://localhost:9000/store/booking-carts \
  -H "Content-Type: application/json" \
  -d '{
    "region_id": "reg_xxx"
  }'

Step 7: Add Booking to Cart (Storefront)

Customer adds the booking to their cart:

curl -X POST http://localhost:9000/store/booking-carts/[cartId]/items \
  -H "Content-Type: application/json" \
  -d '{
    "booking_resource_id": "br_01HXXX...",
    "start_date": "2026-02-15T10:00:00Z",
    "end_date": "2026-02-15T14:00:00Z"
  }'

This creates a temporary allocation (hold) on the resource.

Step 8: Complete Booking (Storefront)

Customer completes the booking, which creates an order and confirms the booking:

curl -X POST http://localhost:9000/store/booking-carts/[cartId]/complete

The booking is now confirmed, and the resource allocation is finalized.

License

Apache 2.0

Author

RSC Labs (https://rsoftcon.com)

Repository

https://github.com/RSC-Labs/medusa-booking-system