Skip to main content
The Events API provides a comprehensive set of queries and mutations for managing events in the Ticket Hub platform. This API enables event creation, updates, cancellation, and searching functionality.

​
Available Endpoints

​
Mutations

Create Event

Create a new event with tickets

Update Event

Modify existing event details

Cancel Event

Cancel an event and clear waiting lists

​
Queries

Search Events

Search events by name, description, or location

Get Events

Retrieve all active events

Get Event by ID

Fetch a specific event by ID

Get Event Availability

Check ticket availability for an event

​
Event Object Structure

All event endpoints work with the following event object schema:
​
_id
Id<'events'>
required
Unique identifier for the event
​
name
string
required
Name of the event
​
description
string
required
Detailed description of the event
​
location
string
required
Physical location where the event takes place
​
eventDate
number
required
Event date and time stored as Unix timestamp in milliseconds
​
price
number
required
Price per ticket in dollars (minimum: 0)
​
totalTickets
number
required
Total number of tickets available for the event (minimum: 1)
​
userId
string
required
ID of the user who created the event (event organizer)
​
imageStorageId
Id<'_storage'>
Reference to the stored event image
​
is_cancelled
boolean
Whether the event has been cancelled

​
Key Concepts

​
Event States

Events can be in one of the following states:
  • Active: Normal operating state, accepts ticket purchases
  • Cancelled: Event has been cancelled (is_cancelled: true), no longer visible in listings
  • Past: Event date has passed but event is still in the system

​
Ticket Availability

Ticket availability is calculated as: 
availableSpots = totalTickets - (purchasedCount + activeOffers)
Where:
  • purchasedCount: Tickets with status “valid” or “used”
  • activeOffers: Waiting list entries with status “offered” and non-expired offers

​
Validation Rules

All event mutations enforce the following validation rules:
  • Event name, description, and location cannot be empty
  • Event date must be stored as a timestamp (milliseconds since epoch)
  • Price must be 0 or greater
  • Total tickets must be at least 1
  • When updating, total tickets cannot be reduced below the number already sold

​
Common Use Cases

​
Creating an Event

import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

const createEvent = useMutation(api.events.create);

const eventId = await createEvent({
  name: "Summer Music Festival",
  description: "Annual outdoor music festival featuring local artists",
  location: "Central Park Amphitheater",
  eventDate: new Date("2026-07-15").getTime(),
  price: 45.00,
  totalTickets: 500,
  userId: user.id
});

​
Searching for Events

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

const searchResults = useQuery(api.events.search, { 
  searchTerm: "music" 
});

​
Checking Availability

const availability = useQuery(api.events.getEventAvailability, { 
  eventId: "event_id_here" 
});

if (availability?.isSoldOut) {
  // Show sold out message
} else {
  // Show remaining tickets: availability.remainingTickets
}

​
Error Handling

All mutations can throw the following errors:
  • “Event not found”: The specified event ID doesn’t exist
  • “Event is no longer active”: Attempting to modify a cancelled event
  • Validation errors: When input parameters don’t meet requirements
Always wrap API calls in try-catch blocks: 
try {
  await updateEvent({ eventId, ...updates });
  toast.success("Event updated successfully");
} catch (error) {
  console.error("Failed to update event:", error);
  toast.error("Failed to update event. Please try again.");
}

Build docs developers (and LLMs) love

Get started for freeTalk to us