Get Ticket Categories & Pricing

Fetch available ticket categories with pricing information for a specific experience (event or cinema movie).

GET /api/v1/merpi/experience/tickets/{experience_id}

This endpoint returns all available ticket types and their pricing for a specific experience. Use this endpoint to:

• Display ticket prices to customers before booking

• Show available ticket categories (Regular, VIP, Premium, etc.)

• Check seat availability via slots_remaining

• Understand pricing breakdown including ticket price, convenience fees, and merchant commissions

• Validate ticket availability before initiating checkout

This is the primary endpoint for retrieving ticket pricing information. Always call this endpoint before displaying ticket purchase options to customers.

Retrieve Ticket Categories and Pricing

get

Fetch a list of ticket categories available for a specific experience with complete pricing information.

This endpoint returns:

• All ticket types (Regular, VIP, Premium, etc.)

• Total price customers pay

• Detailed price breakdown (base price, convenience fee, merchant commission)

• Available ticket slots

• Free ticket indicators

CRITICAL: Always validate slots_remaining before allowing ticket purchases.

Path parameters

experience_idstring · uuidRequired

Unique identifier for the experience (UUID format). Works for both regular experiences and cinema experiences.

Example: 9b0c2340-8274-4e9b-b7b8-a652dbb652eb

Responses

200

Successfully retrieved ticket categories and pricing

application/json

successbooleanOptional

Indicates whether the request was successful.

statusintegerOptional

HTTP status code (200 for success).

messagestringOptional

Human-readable description of the response.

400

Bad Request - Invalid experience ID format

application/json

404

Not Found - Experience doesn't exist

application/json

500

Internal Server Error

application/json

get

/api/v1/merpi/experience/tickets/{experience_id}

HTTPcURLJavaScriptPython

GET /api/v1/merpi/experience/tickets/{experience_id} HTTP/1.1
Accept: */*

{
  "success": true,
  "status": 200,
  "message": "Success",
  "data": {
    "tickets": [
      {
        "id": "3161487b-f3f7-4b7d-a92c-a09bfaf11347",
        "title": "Regular",
        "price": 2100,
        "free": false,
        "slots_remaining": 3454,
        "price_breakdown": {
          "ticket_price": 2000,
          "convenience_fee": 40,
          "merchant_commission": 60
        },
        "experience": {
          "id": "9b0c2340-8274-4e9b-b7b8-a652dbb652eb",
          "title": "Batman: The Yahoo Junction Menace 4"
        }
      },
      {
        "id": "ee1cbdd5-b581-4363-aab0-050dca412b17",
        "title": "VIP",
        "price": 5250,
        "free": false,
        "slots_remaining": 3455,
        "price_breakdown": {
          "ticket_price": 5000,
          "convenience_fee": 100,
          "merchant_commission": 150
        },
        "experience": {
          "id": "9b0c2340-8274-4e9b-b7b8-a652dbb652eb",
          "title": "Batman: The Yahoo Junction Menace 4"
        }
      }
    ]
  }
}

Path Parameters

Parameter	Type	Required	Description
experience_id	string (UUID)	Yes	Unique identifier for the experience. Works for both regular experiences and cinema experiences.

Response Format

Root Response Object

Field	Type	Description
success	boolean	Indicates whether the request was successful.
status	integer	HTTP status code (200 for successful requests).
message	string	Human-readable description of the response.
data	object	Container object holding ticket data.

Data Object

Field	Type	Description
tickets	array	Array of ticket category objects. Each represents a different ticket type available for purchase.

Ticket Object

Field	Type	Description
id	string (UUID)	Unique identifier for this ticket category. Use this ID when creating bookings.
title	string	Display name of the ticket category (e.g., "Regular", "VIP", "Premium", "Student").
price	integer	Total price in local currency (NGN for Nigeria). This is what the customer pays. Includes ticket price, convenience fee, and merchant commission.
free	boolean	Indicates if this ticket type is free. When true, price will be 0.
slots_remaining	integer	Number of tickets still available for this category. Check this before allowing purchases.
price_breakdown	object	Detailed breakdown of the total price showing individual components.
experience	object	Reference to the experience this ticket belongs to.

Price Breakdown Object

New Field: The price_breakdown object provides transparency in pricing by showing how the total price is calculated.

Field	Type	Description
ticket_price	integer	Base ticket price set by the business/organizer.
convenience_fee	integer	Platform convenience fee charged.
merchant_commission	integer	Commission fee charged for the merchant (informational - already included in total).

Important: price = ticket_price + convenience_fee + merchant_commission

The total price is what customers pay. The price_breakdown shows how this total is calculated.

Experience Reference Object

Field	Type	Description
id	string (UUID)	Unique identifier for the experience.
title	string	Title/name of the experience.

Validating Ticket Availability

CRITICAL - Always Validate Before Checkout

Check slots_remaining before allowing ticket purchases:

• If slots_remaining is 0, the ticket category is sold out

• If slots_remaining is less than requested quantity, show error

• Refresh ticket data before finalizing purchases (availability can change)

JavaScript Validation

function canPurchaseTickets(ticket, quantity) {
  if (ticket.slots_remaining === 0) {
    return {
      canPurchase: false,
      reason: `${ticket.title} tickets are sold out`
    };
  }
  
  if (ticket.slots_remaining < quantity) {
    return {
      canPurchase: false,
      reason: `Only ${ticket.slots_remaining} ${ticket.title} tickets remaining`
    };
  }
  
  return {
    canPurchase: true,
    reason: null
  };
}

// Usage
const validation = canPurchaseTickets(ticket, 5);
if (!validation.canPurchase) {
  alert(validation.reason);
}

Python Validation

def can_purchase_tickets(ticket, quantity):
    if ticket['slots_remaining'] == 0:
        return {
            'can_purchase': False,
            'reason': f"{ticket['title']} tickets are sold out"
        }
    
    if ticket['slots_remaining'] < quantity:
        return {
            'can_purchase': False,
            'reason': f"Only {ticket['slots_remaining']} {ticket['title']} tickets remaining"
        }
    
    return {
        'can_purchase': True,
        'reason': None
    }

Working with Free Tickets

When free: true:

function displayTicketPrice(ticket) {
  if (ticket.free) {
    return 'FREE';
  }
  return `₦${ticket.price.toLocaleString()}`;
}

function handleFreeTickets(ticket, quantity) {
  if (ticket.free && ticket.slots_remaining >= quantity) {
    // Free tickets still need booking
    return {
      total: 0,
      message: `${quantity} free tickets reserved`
    };
  }
}

Integration Workflow

Complete Ticket Selection Flow

// 1. Fetch experience details
const experience = await fetchExperienceDetails(experienceId);

// 2. Validate experience is still active (for regular experiences)
if (!experience.cinema) {
  const status = validateExperienceDate(experience);
  if (!status.canPurchase) {
    return showError('Event has ended');
  }
}

// 3. Fetch ticket options
const ticketsResponse = await fetch(`/api/v1/merpi/experience/tickets/${experienceId}`);
const ticketsData = await ticketsResponse.json();

// 4. Display tickets to user
displayTicketOptions(ticketsData.data.tickets);

// 5. User selects tickets
const selectedTickets = getUserSelection();

// 6. Validate availability
const validation = validateTicketAvailability(ticketsData.data.tickets, selectedTickets);
if (!validation.valid) {
  return showError(validation.message);
}

// 7. Calculate total
const { total, breakdown } = calculateTotal(selectedTickets);

// 8. Show confirmation with price breakdown
showCheckoutSummary(total, breakdown);

// 9. Proceed to booking endpoint
createBooking(experienceId, selectedTickets);

Response Caching Considerations

Important: Ticket availability (slots_remaining) can change rapidly, especially for popular events.

Recommendations:

• Cache ticket data for maximum 1-2 minutes

• Always fetch fresh data before checkout

• Implement optimistic UI with server validation

• Handle "sold out" errors gracefully during booking {% endhint %}

class TicketCache {
  constructor(ttlSeconds = 60) {
    this.cache = new Map();
    this.ttl = ttlSeconds * 1000;
  }
  
  async get(experienceId) {
    const cached = this.cache.get(experienceId);
    const now = Date.now();
    
    if (cached && (now - cached.timestamp) < this.ttl) {
      return cached.data;
    }
    
    // Fetch fresh data
    const response = await fetch(`/api/v1/merpi/experience/tickets/${experienceId}`);
    const data = await response.json();
    
    this.cache.set(experienceId, {
      data: data.data.tickets,
      timestamp: now
    });
    
    return data.data.tickets;
  }
}

const ticketCache = new TicketCache(60); // 60 second cache

Next Steps

After fetching ticket information:

1. Display ticket options - Show all categories with prices and availability

2. Validate selection - Check slots_remaining before allowing checkout

3. Create booking - Use the ticket id when calling the booking endpoint

4. Handle sold out - Gracefully handle cases where slots_remaining is 0

Related Endpoints

• Get Experience Details - Fetch complete experience information before showing tickets

• Get Cinema Experience Details - For cinema-specific movie details

• Create Booking - Book selected tickets (use ticket id from this response)

• Get List of Experiences - Browse available events and movies