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

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Medusa Booking System Plugin

Introduction

Features

Core Capabilities

Resource Types

Availability System

Booking Rules (Policies)

Pricing System

Installation

Prerequisites

Step 1: Add the Package

Step 2: Configure the Plugin

Step 3: Generate Migrations

Step 4: Run Migrations

API Reference

Store APIs (Public)

Booking Resources

Booking Carts

Admin APIs (Authenticated)

Booking Resources

Booking Rules

Availability Rules

Pricing

Bookings

Admin UI (Booking)

Complete Scenario Walkthrough

Step 1: Create a Booking Resource

Step 2: Create Availability Rules

Step 3: Create Pricing Configuration

Step 4: Publish the Resource

Step 5: Check Availability and Resource (Storefront)

Step 6: Create Booking Cart (Storefront)

Step 7: Add Booking to Cart (Storefront)

Step 8: Complete Booking (Storefront)

License

Author

Repository

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages