Browse registration opportunities

Registration opportunities are the specific sessions, classes, or events that people sign up for within a program. Each has its own schedule, pricing, capacity, and registration window. This guide shows you how to list registration opportunities, filter by program or availability, and load pricing and signup details.

Before you begin

Authentication — you need a valid API key.
Fetch program information — find the program ID you want to browse sessions for.

1. List registration opportunities for a program

To show what sessions are available under a specific program, filter by parent_program_id. This is the most common starting point — a user has selected a program and wants to see what they can register for.

curl -X GET "https://api.getcommunal.com/api/programs?filter[parent_program_id]=42" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The response includes a paginated list of registration opportunities with scheduling, capacity, and pricing details for each session.

{
  "data": [
    {
      "id": 101,
      "name": "Session A — Morning",
      "parent_program_id": 42,
      "status": "Active",
      "event_start_date": "2025-06-15T00:00:00.000000Z",
      "event_end_date": "2025-06-20T00:00:00.000000Z",
      "readable_event_start_date": "June 15, 2025",
      "readable_event_start_time": "9:00 AM",
      "class_limit": 25,
      "spots_remaining": 8,
      "free": false
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 30, "total": 4 }
}

2. Filter by availability and status

You can narrow results to only sessions that are currently accepting registration, upcoming, or past. Combine filters to match your UI needs.

To show only sessions a user can still register for:

curl -X GET "https://api.getcommunal.com/api/programs?filter[parent_program_id]=42&filter[can_register]=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Available filters include status (active, upcoming, past, ongoing, archived — comma-separated), can_register (currently open for registration), upcoming (registration opens in the future), past (event has ended), with_participants (has signups), and query (searches by name). Sort with sort=event_start_date or prefix with - for descending.

3. Get a single registration opportunity

Fetch full details for a specific session when building a detail or checkout page. The show endpoint returns additional computed fields like capacity status and user-specific pricing.

curl -X GET "https://api.getcommunal.com/api/programs/101" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The response includes fields like is_full, spots_remaining, waitlist_enabled, and registration window dates — everything you need to decide whether to show a "Register" or "Join waitlist" button.

Use the include parameter to load pricing tiers, the parent program, signups, or attendance sheets in a single request. This avoids extra round trips when building detail views.

curl -X GET "https://api.getcommunal.com/api/programs/101?include=prices,parentProgram&append=signup_count" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The prices include returns an array of pricing tiers. Add prices.membership to see which tiers are membership-specific. The append=signup_count parameter adds the current signup count as a computed field.

Note: The show endpoint supports deeper includes than the list endpoint. Includes like prices.membership, prices.plan, prices.schedule_config, and metadata are only available when fetching a single registration opportunity.

What's next

Retrieve program signups — list and filter signups for a session
View attendance — load attendance sheets and records for sessions
See the Registration Opportunity endpoints in the API Reference for the complete list of fields, filters, and includes

Fetch program information

Retrieve program signups