Reservations API

The Reservations API handles the complete booking flow: reserve seats with timeout protection, then confirm with payment details.

The Booking Flow

1. Reserve → Create pending registration with timeout (30min default)
2. Payment → Process payment through your system
3. Confirm → Complete booking with payment reference

Reserve Seats

POST /api/v1/events/{id}/reserve

Creates a temporary seat reservation with automatic timeout.

Request Body

{
  "contact_name": "María García",
  "contact_email": "maria@example.com",
  "contact_phone": "+57 300 123 4567",
  "number_of_attendees": 2
}

Example Request

curl -X POST "https://your-org.calendi.me/api/v1/events/123/reserve" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_name": "María García",
    "contact_email": "maria@example.com",
    "contact_phone": "+57 300 123 4567",
    "number_of_attendees": 2
  }'

Success Response

{
  "success": true,
  "data": {
    "registration_id": "456",
    "reserved_until": "2024-12-10T10:30:00.000Z",
    "payment_amount": 100000,
    "expires_in_minutes": 30,
    "message": "Reservation created successfully. Please complete payment within 30 minutes."
  }
}

Error Responses

// Insufficient seats
{
  "success": false,
  "error": "Insufficient seats available. Available: 1, Requested: 2"
}

// Event not found
{
  "success": false,
  "error": "Event not found or inactive"
}

// Invalid email
{
  "success": false,
  "error": "Invalid email format"
}

Confirm Registration

POST /api/v1/registrations/{id}/confirm

Confirms a pending reservation with payment details.

Request Body

{
  "payment_reference": "PAY_123456789",
  "payment_amount": 100000
}

Example Request

curl -X POST "https://your-org.calendi.me/api/v1/registrations/456/confirm" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_reference": "PAY_123456789",
    "payment_amount": 100000
  }'

Success Response

{
  "success": true,
  "data": {
    "registration_id": "456",
    "status": "confirmed",
    "confirmed_at": "2024-12-10T10:15:00.000Z",
    "contact_email": "maria@example.com",
    "number_of_attendees": 2,
    "payment_reference": "PAY_123456789",
    "message": "Registration confirmed successfully. Confirmation details will be sent to the provided email."
  }
}

Error Responses

// Registration expired
{
  "success": false,
  "error": "Registration has expired"
}

// Already confirmed
{
  "success": false,
  "error": "Cannot confirm registration with status: confirmed"
}

// Capacity exceeded (race condition)
{
  "success": false,
  "error": "Event capacity exceeded. Registration cannot be confirmed."
}

Complete Example Flow

Step 1: Find Available Event

# Search for grade 2 events at location 1
curl -X GET "https://your-org.calendi.me/api/v1/events?location_id=1&grade_id=2" \
  -H "X-API-Key: your-api-key"

# Response shows event 123 has 5 available seats

Step 2: Reserve Seats

# Reserve 2 seats for family
curl -X POST "https://your-org.calendi.me/api/v1/events/123/reserve" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_name": "María García",
    "contact_email": "maria@example.com",
    "number_of_attendees": 2
  }'

# Response: registration_id "456", expires in 30 minutes

Step 3: Process Payment

// In your application - process payment
const payment = await processPayment({
  amount: 100000,
  description: "Immersion Day - 2 attendees",
  customer_email: "maria@example.com"
})

// Get payment reference: "PAY_123456789"

Step 4: Confirm Booking

# Confirm with payment details
curl -X POST "https://your-org.calendi.me/api/v1/registrations/456/confirm" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_reference": "PAY_123456789",
    "payment_amount": 100000
  }'

# Response: status "confirmed", booking complete!

Important Notes

Reservation Timeout

• Default timeout: 30 minutes
• Timeout varies by event (check reservation_timeout_minutes)
• Expired reservations are automatically marked as expired
• Always confirm before timeout to secure seats

Race Conditions

• Multiple users can reserve simultaneously
• Confirmation does final capacity check
• First to confirm gets the seats
• Build retry logic for high-demand events

Payment Integration

• Calendi doesn't process payments
• Use your preferred payment processor
• Store payment reference for reconciliation
• Amount validation is recommended but flexible

Email Notifications

• Confirmation emails are sent automatically
• Include booking details and event information
• Customize email templates in dashboard settings

Status Lifecycle

pending → confirmed
   ↓
expired (if timeout reached)

• pending: Reservation active, awaiting payment
• confirmed: Payment processed, seats secured
• expired: Timeout reached, seats released

Next: Error Handling →