Skip to main content

Ticket Management API

Ticket Management API

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-02-18 Version: v1.1

Base URL: https://your-api-domain.com/api/v1/e-events/tickets

Short Description: The Ticket Management API allows event organizers to define and manage ticket types for their events on NextGate. Organizers can create multiple ticket tiers (e.g. VIP, Early Bird, General Admission), control pricing, capacity, sales periods, visibility, and sales channels. Tickets are always scoped to a specific event and follow the event's lifecycle from DRAFT through to PUBLISHED.

Hints:

  • Tickets can only be created and fully edited while the event is in DRAFT status. Once published, only capacity and status changes are allowed.
  • For HYBRID events, you must create at least one IN_PERSON ticket and one ONLINE ticket before the event can be published.
  • Ticket names must be unique per event per attendance mode — you cannot have two IN_PERSON tickets both named "VIP Pass" on the same event.
  • DONATION tickets are restricted to ONLINE_ONLY sales channel and a maximum of 1 ticket per order and per user. They have no fixed price — the buyer freely chooses their donation amount at checkout.
  • The ticket sales window must fall within the event's registration window. Sales cannot start before registration opens or end after registration closes.
  • The minimum gap between salesStartDateTime and salesEndDateTime is 30 minutes.
  • Soft deletion is used — a ticket can only be deleted if zero tickets have been sold. Otherwise, close it using the status endpoint.
  • All datetimes must be in ISO 8601 / ZonedDateTime format (e.g. 2025-08-10T09:00:00+03:00).

User Journey

The diagram below represents the typical flow an event organizer follows when setting up and managing tickets for their event.

  [Organizer creates event in DRAFT status]
                    |
                    | (Event must be DRAFT before any ticket work)
                    v
  . . . . . . . . . . . . . . . . . . . . . . .
  .                                             .
  .   TICKET SETUP PHASE                        .
  .                                             .
  .   [Create ticket types]                     .
  .      |-- General Admission (PAID)           .
  .      |-- VIP Pass (PAID)                    .
  .      |-- Student Discount (PAID)            .
  .      |-- Free Entry (FREE)                  .
  .      '-- Support the Artist (DONATION)      .
  .                                             .
  . . . . . . . . . . . . . . . . . . . . . . .
                    |
                    v
  [Review all ticket types via Get All Tickets]
                    |
                    v
  . . . . . . . . . . . . . . . . . . . . . . .
  .                                             .
  .   ADJUSTMENTS PHASE (still DRAFT)           .
  .                                             .
  .   Need to fix details?                      .
  .      --> Update Ticket (name, price, etc.)  .
  .                                             .
  .   Wrong capacity?                           .
  .      --> Update Ticket Capacity             .
  .                                             .
  .   Ticket no longer needed?                  .
  .      --> Delete Ticket (only if 0 sold)     .
  .                                             .
  . . . . . . . . . . . . . . . . . . . . . . .
                    |
                    v
  [Event published — tickets go live for buyers]
                    |
                    v
  . . . . . . . . . . . . . . . . . . . . . . .
  .                                             .
  .   LIVE EVENT PHASE                          .
  .                                             .
  .   Ticket sells out?                         .
  .      --> System auto-sets SOLD_OUT          .
  .      --> Organizer can increase capacity    .
  .          to reactivate it                   .
  .                                             .
  .   Want to pause sales temporarily?          .
  .      --> Update Status to INACTIVE          .
  .                                             .
  .   Want to stop sales permanently?           .
  .      --> Update Status to CLOSED            .
  .                                             .
  . . . . . . . . . . . . . . . . . . . . . . .

Sales Window Rules

Ticket sales must respect three nested time windows:

Event:          [eventStartDateTime ─────────────── eventEndDateTime]
Registration:         [registrationOpensAt ──── registrationClosesAt]
Ticket Sales:              [salesStartDateTime ── salesEndDateTime]

Rules enforced:

  • salesStartDateTime cannot be in the past
  • salesEndDateTime cannot be in the past
  • salesEndDateTime must be after salesStartDateTime
  • Minimum gap between sales start and end is 30 minutes
  • salesStartDateTime must be on or after registrationOpensAt
  • salesStartDateTime cannot be after registrationClosesAt
  • salesEndDateTime cannot be after registrationClosesAt
  • Neither date can be after eventEndDateTime

Standard Response Format

All API responses follow a consistent structure:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field Type Description
success boolean true for successful operations, false for errors
httpStatus string HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message string Human-readable description of the operation result
action_time string ISO 8601 timestamp of when the response was generated
data object/string Response payload on success; error detail on failure

HTTP Method Badges

  • GET — GET
  • POST — POST
  • PUT — PUT
  • PATCH — PATCH
  • DELETE — DELETE

Enum Reference

TicketPricingType

Value Description
PAID Standard paid ticket. Price must be greater than 0.00
FREE Free entry. Price must be exactly 0.00
DONATION Supporter ticket. No fixed price — buyer freely enters their donation amount at checkout. Restricted to ONLINE_ONLY channel, max 1 per order and per user. price is not returned in the response for DONATION tickets

SalesChannel

Value Description
EVERYWHERE Available both online and at the door
ONLINE_ONLY Available for purchase online only
AT_DOOR_ONLY Available for purchase at the venue door only

AttendanceMode

Value Description
IN_PERSON Ticket grants physical entry to the venue
ONLINE Ticket grants access to the online/virtual stream

Note: For IN_PERSON events, only IN_PERSON tickets are allowed. For ONLINE events, only ONLINE tickets are allowed. For HYBRID events, both are permitted and at least one of each is required before publishing.

TicketVisibility

Value Description
VISIBLE Always shown to the public
HIDDEN Never shown to buyers (organizer use only)
HIDDEN_WHEN_NOT_ON_SALE Only visible while the ticket is actively on sale
CUSTOM_SCHEDULE Shown only within a defined date/time window. Requires visibilityStartDate and visibilityEndDate

TicketStatus

Value Description
ACTIVE Ticket is live and available for purchase
INACTIVE Temporarily paused. Organizer can reactivate
CLOSED Permanently stopped. Cannot be reopened
SOLD_OUT System-managed. Set automatically when ticketsSold >= totalTickets. Can revert to ACTIVE if capacity is increased
DELETED Soft-deleted. Only possible if zero tickets were sold. Use the Delete endpoint — cannot be set via status update

PricingSummary (on Event responses)

Value Description
FREE All tickets on the event are free
PAID All tickets on the event are paid
DONATION All tickets on the event are donation-based
MIXED The event has a combination of free, paid, and/or donation tickets

Endpoints

1. Create Ticket

Purpose: Creates a new ticket type for a specific event. The event must be in DRAFT status. The authenticated user must be the event organizer.

Endpoint: POST {base_url}/{eventId}

Access Level: 🔒 Protected (Event organizer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event to add the ticket to Must be a valid UUID

Request Body Parameters:

Parameter Type Required Description Validation
name string Yes Ticket name (e.g. "VIP Pass", "Early Bird") Min: 2, Max: 100 characters. Must be unique per event per attendance mode
description string No Optional description of what the ticket includes Max: 500 characters
price decimal Conditional Ticket price. Use 0.00 for FREE tickets. Omit or send 0.00 for DONATION tickets Min: 0.00. PAID → must be > 0.00. FREE → must be 0.00. DONATION → ignored, system sets to 0.00
ticketPricingType string Yes Pricing model Enum: PAID, FREE, DONATION
salesChannel string Yes Where the ticket can be purchased. DONATION tickets must use ONLINE_ONLY Enum: EVERYWHERE, ONLINE_ONLY, AT_DOOR_ONLY. Defaults to EVERYWHERE
totalQuantity integer Yes Total number of tickets available Min: 1, Max: 1,000,000
salesStartDateTime datetime No When sales open. Must be within registration window. If omitted, sales begin at registration open ISO 8601 ZonedDateTime. Cannot be before registrationOpensAt or after registrationClosesAt
salesEndDateTime datetime No When sales close. Must be within registration window ISO 8601 ZonedDateTime. Must be after salesStartDateTime with at least 30 minutes gap. Cannot be after registrationClosesAt
minQuantityPerOrder integer No Minimum tickets a buyer must purchase per order Min: 1. Defaults to 1
maxQuantityPerOrder integer No Maximum tickets a buyer can purchase per order. DONATION tickets must be 1 Min: 1, Max: 100. Must be ≥ minQuantityPerOrder. Leave null for no limit
maxQuantityPerUser integer No Maximum tickets a single user can purchase across all orders. DONATION tickets must be 1 Min: 1, Max: 1000. Must be ≥ maxQuantityPerOrder. Leave null for no limit
visibility string Yes Controls whether the ticket is shown to buyers Enum: VISIBLE, HIDDEN, HIDDEN_WHEN_NOT_ON_SALE, CUSTOM_SCHEDULE. Defaults to VISIBLE
visibilityStartDate datetime No When the ticket becomes visible. Required if visibility is CUSTOM_SCHEDULE ISO 8601 ZonedDateTime
visibilityEndDate datetime No When the ticket stops being visible. Required if visibility is CUSTOM_SCHEDULE. Must be after visibilityStartDate ISO 8601 ZonedDateTime
attendanceMode string Yes Whether this ticket is for physical or online attendance Enum: IN_PERSON, ONLINE. Must match the event format
inclusiveItems array of strings No List of perks included with this ticket (e.g. "Free T-Shirt", "Meet & Greet") Max: 50 items. Each item: max 200 characters, cannot be blank

Request JSON Sample (PAID):

{
  "name": "VIP Pass",
  "description": "Full weekend access with backstage entry and a complimentary gift bag.",
  "price": 150.00,
  "ticketPricingType": "PAID",
  "salesChannel": "EVERYWHERE",
  "totalQuantity": 200,
  "salesStartDateTime": "2026-03-18T08:00:00+03:00",
  "salesEndDateTime": "2026-04-17T23:59:00+03:00",
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 4,
  "maxQuantityPerUser": 4,
  "visibility": "VISIBLE",
  "attendanceMode": "IN_PERSON",
  "inclusiveItems": [
    "Backstage access",
    "Complimentary gift bag",
    "Priority seating"
  ]
}

Request JSON Sample (DONATION):

{
  "name": "Support the Artist",
  "description": "Show your support — donate any amount you choose at checkout.",
  "price": 0.00,
  "ticketPricingType": "DONATION",
  "salesChannel": "ONLINE_ONLY",
  "totalQuantity": 500,
  "salesStartDateTime": "2026-03-18T08:00:00+03:00",
  "salesEndDateTime": "2026-04-17T23:59:00+03:00",
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 1,
  "maxQuantityPerUser": 1,
  "visibility": "VISIBLE",
  "attendanceMode": "IN_PERSON"
}

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "Ticket created successfully",
  "action_time": "2025-02-18T10:30:45",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventId": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
    "name": "VIP Pass",
    "description": "Full weekend access with backstage entry and a complimentary gift bag.",
    "price": 150.00,
    "ticketPricingType": "PAID",
    "salesChannel": "EVERYWHERE",
    "totalTickets": 200,
    "ticketsSold": 0,
    "ticketsRemaining": 200,
    "ticketsAvailable": 200,
    "isSoldOut": false,
    "salesStartDateTime": "2026-03-18T05:00:00Z",
    "salesEndDateTime": "2026-04-17T20:59:00Z",
    "isOnSale": false,
    "minQuantityPerOrder": 1,
    "maxQuantityPerOrder": 4,
    "maxQuantityPerUser": 4,
    "visibility": "VISIBLE",
    "visibilityStartDate": null,
    "visibilityEndDate": null,
    "isCurrentlyVisible": true,
    "attendanceMode": "IN_PERSON",
    "inclusiveItems": [
      "Backstage access",
      "Complimentary gift bag",
      "Priority seating"
    ],
    "status": "ACTIVE",
    "createdAt": "2025-02-18T10:30:45+03:00",
    "updatedAt": null,
    "createdBy": "john_organizer",
    "updatedBy": null
  }
}

Note on DONATION response: For DONATION tickets, the price field is null in the response. The buyer enters their own amount at checkout.

Success Response Fields:

Field Description
id Unique identifier for this ticket type
eventId The event this ticket belongs to
name Ticket name
description Ticket description
price Ticket price. null for DONATION tickets
ticketPricingType Pricing model: PAID, FREE, or DONATION
salesChannel Where the ticket can be purchased
totalTickets Total number of tickets created
ticketsSold Number of tickets purchased so far
ticketsRemaining totalTickets - ticketsSold
ticketsAvailable Same as ticketsRemaining (current available quantity)
isSoldOut true if ticketsSold >= totalTickets
salesStartDateTime When ticket sales open
salesEndDateTime When ticket sales close
isOnSale Calculated: true if ticket is ACTIVE and currently within the sales window
minQuantityPerOrder Minimum per order
maxQuantityPerOrder Maximum per order (null = no limit)
maxQuantityPerUser Maximum per user across all orders (null = no limit)
visibility Visibility setting
visibilityStartDate Start of custom visibility window
visibilityEndDate End of custom visibility window
isCurrentlyVisible Calculated: whether the ticket is currently visible to buyers
attendanceMode IN_PERSON or ONLINE
inclusiveItems List of perks included with the ticket
status Ticket status: ACTIVE, INACTIVE, CLOSED, SOLD_OUT, DELETED
createdAt Timestamp when the ticket was created
updatedAt Timestamp of last update (null if never updated)
createdBy Username of the organizer who created the ticket
updatedBy Username of last person who updated the ticket (null if never updated)

Possible Error Responses:

Status Scenario
401 No or expired token
403 Authenticated user is not the event organizer
404 Event not found
400 Event is not in DRAFT status
400 Ticket name already exists for this event and attendance mode
422 Validation errors (missing required fields, invalid price, sales window outside registration window, gap less than 30 minutes, etc.)

Error Response Examples:

Event Not in Draft (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Tickets can only be created for events in DRAFT status. Current status: PUBLISHED",
  "action_time": "2025-02-18T10:30:45",
  "data": "Tickets can only be created for events in DRAFT status. Current status: PUBLISHED"
}

Duplicate Ticket Name (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "A ticket with name 'VIP Pass' and attendance mode 'IN_PERSON' already exists for this event",
  "action_time": "2025-02-18T10:30:45",
  "data": "A ticket with name 'VIP Pass' and attendance mode 'IN_PERSON' already exists for this event"
}

Sales Window Outside Registration Window (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Sales start date cannot be before registration opens (2026-03-18T05:00:00Z)",
  "action_time": "2026-02-18T10:30:45",
  "data": {
    "stage": "TICKETS",
    "message": "Sales start date cannot be before registration opens (2026-03-18T05:00:00Z)"
  }
}

Sales Period Too Short (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Sales period must be at least 30 minutes",
  "action_time": "2026-02-18T10:30:45",
  "data": {
    "stage": "TICKETS",
    "message": "Sales period must be at least 30 minutes"
  }
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-02-18T10:30:45",
  "data": {
    "name": "Ticket name is required",
    "price": "Price must be zero or positive",
    "ticketPricingType": "Ticket type is required"
  }
}

2. Update Ticket

Purpose: Updates the details of an existing ticket type. The event must still be in DRAFT status. All fields are optional — only the fields you send will be updated. Omitted fields keep their current values.

Endpoint: PUT {base_url}/{ticketId}

Access Level: 🔒 Protected (Event organizer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
ticketId UUID Yes The ticket to update Must be a valid UUID

Request Body Parameters:

Parameter Type Required Description Validation
name string No Updated ticket name Min: 2, Max: 100 characters. Must remain unique per event per attendance mode
description string No Updated description Max: 500 characters
price decimal No Updated price. Ignored for DONATION tickets — system forces to 0.00 Min: 0.00. Must be consistent with ticketPricingType rules
ticketPricingType string No Updated pricing model Enum: PAID, FREE, DONATION
salesChannel string No Updated sales channel. DONATION tickets must be ONLINE_ONLY Enum: EVERYWHERE, ONLINE_ONLY, AT_DOOR_ONLY
totalQuantity integer No Updated total capacity Min: 1, Max: 1,000,000
salesStartDateTime datetime No Updated sales open time. Must be within registration window ISO 8601 ZonedDateTime. Cannot be before registrationOpensAt or after registrationClosesAt
salesEndDateTime datetime No Updated sales close time. Must be within registration window ISO 8601 ZonedDateTime. Must be after salesStartDateTime with at least 30 minutes gap. Cannot exceed registrationClosesAt
minQuantityPerOrder integer No Updated minimum per order Min: 1
maxQuantityPerOrder integer No Updated maximum per order. DONATION must be 1 Min: 1, Max: 100
maxQuantityPerUser integer No Updated maximum per user. DONATION must be 1 Min: 1, Max: 1000
attendanceMode string No Updated attendance mode Enum: IN_PERSON, ONLINE. Must match event format rules
inclusiveItems array of strings No Full replacement list of inclusive perks Max: 50 items. Each: max 200 characters, cannot be blank
visibility string No Updated visibility Enum: VISIBLE, HIDDEN, HIDDEN_WHEN_NOT_ON_SALE, CUSTOM_SCHEDULE
visibilityStartDate datetime No Updated visibility start Required if changing to CUSTOM_SCHEDULE
visibilityEndDate datetime No Updated visibility end Required if changing to CUSTOM_SCHEDULE. Must be after start

Request JSON Sample:

{
  "name": "VIP Weekend Pass",
  "price": 175.00,
  "maxQuantityPerOrder": 2,
  "inclusiveItems": [
    "Backstage access",
    "Complimentary gift bag",
    "Priority seating",
    "Artist meet & greet"
  ]
}

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket updated successfully",
  "action_time": "2025-02-18T11:00:00",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventId": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
    "name": "VIP Weekend Pass",
    "description": "Full weekend access with backstage entry and a complimentary gift bag.",
    "price": 175.00,
    "ticketPricingType": "PAID",
    "salesChannel": "EVERYWHERE",
    "totalTickets": 200,
    "ticketsSold": 0,
    "ticketsRemaining": 200,
    "ticketsAvailable": 200,
    "isSoldOut": false,
    "salesStartDateTime": "2026-03-18T05:00:00Z",
    "salesEndDateTime": "2026-04-17T20:59:00Z",
    "isOnSale": false,
    "minQuantityPerOrder": 1,
    "maxQuantityPerOrder": 2,
    "maxQuantityPerUser": 4,
    "visibility": "VISIBLE",
    "visibilityStartDate": null,
    "visibilityEndDate": null,
    "isCurrentlyVisible": true,
    "attendanceMode": "IN_PERSON",
    "inclusiveItems": [
      "Backstage access",
      "Complimentary gift bag",
      "Priority seating",
      "Artist meet & greet"
    ],
    "status": "ACTIVE",
    "createdAt": "2025-02-18T10:30:45+03:00",
    "updatedAt": "2025-02-18T11:00:00+03:00",
    "createdBy": "john_organizer",
    "updatedBy": "john_organizer"
  }
}

Success Response Fields: Same as Create Ticket response fields.

Possible Error Responses:

Status Scenario
401 No or expired token
403 Authenticated user is not the event organizer
404 Ticket not found
400 Event is not in DRAFT status
400 Updated name conflicts with an existing ticket on the same event
422 Validation errors (invalid price, quantity inconsistencies, sales window outside registration window, etc.)

3. Get All Tickets for Event

Purpose: Retrieves a lightweight summary list of all active (non-deleted) tickets for a given event, ordered by creation date ascending.

Endpoint: GET {base_url}/{eventId}

Access Level: 🌐 Public

Authentication: None required

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event to retrieve tickets for Must be a valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Tickets retrieved successfully",
  "action_time": "2025-02-18T10:30:45",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "General Admission",
      "price": 25.00,
      "ticketPricingType": "PAID",
      "salesChannel": "EVERYWHERE",
      "visibility": "VISIBLE",
      "totalTickets": 1000,
      "ticketsSold": 342,
      "ticketsAvailable": 658,
      "isSoldOut": false,
      "attendanceMode": "IN_PERSON",
      "status": "ACTIVE",
      "isOnSale": true
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "VIP Pass",
      "price": 150.00,
      "ticketPricingType": "PAID",
      "salesChannel": "EVERYWHERE",
      "visibility": "VISIBLE",
      "totalTickets": 200,
      "ticketsSold": 200,
      "ticketsAvailable": 0,
      "isSoldOut": true,
      "attendanceMode": "IN_PERSON",
      "status": "SOLD_OUT",
      "isOnSale": false
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-012345678902",
      "name": "Support the Artist",
      "price": null,
      "ticketPricingType": "DONATION",
      "salesChannel": "ONLINE_ONLY",
      "visibility": "VISIBLE",
      "totalTickets": 500,
      "ticketsSold": 120,
      "ticketsAvailable": 380,
      "isSoldOut": false,
      "attendanceMode": "IN_PERSON",
      "status": "ACTIVE",
      "isOnSale": true
    }
  ]
}

Success Response Fields (per item):

Field Description
id Unique identifier for the ticket type
name Ticket name
price Ticket price. null for DONATION tickets
ticketPricingType Pricing model
salesChannel Where it can be purchased
visibility Visibility setting
totalTickets Total quantity created
ticketsSold Quantity sold so far
ticketsAvailable Quantity still available
isSoldOut Whether the ticket is sold out
attendanceMode IN_PERSON or ONLINE
status Current ticket status
isOnSale Whether the ticket is currently purchasable

Possible Error Responses:

Status Scenario
404 Event not found

4. Get Ticket by ID

Purpose: Retrieves the full details of a single ticket type by its ID.

Endpoint: GET {base_url}/{eventId}/{ticketId}

Access Level: 🌐 Public

Authentication: None required

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event the ticket belongs to Must be a valid UUID
ticketId UUID Yes The specific ticket to retrieve Must be a valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket retrieved successfully",
  "action_time": "2025-02-18T10:30:45",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventId": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
    "name": "VIP Pass",
    "description": "Full weekend access with backstage entry and a complimentary gift bag.",
    "price": 150.00,
    "ticketPricingType": "PAID",
    "salesChannel": "EVERYWHERE",
    "totalTickets": 200,
    "ticketsSold": 45,
    "ticketsRemaining": 155,
    "ticketsAvailable": 155,
    "isSoldOut": false,
    "salesStartDateTime": "2026-03-18T05:00:00Z",
    "salesEndDateTime": "2026-04-17T20:59:00Z",
    "isOnSale": true,
    "minQuantityPerOrder": 1,
    "maxQuantityPerOrder": 4,
    "maxQuantityPerUser": 4,
    "visibility": "VISIBLE",
    "visibilityStartDate": null,
    "visibilityEndDate": null,
    "isCurrentlyVisible": true,
    "attendanceMode": "IN_PERSON",
    "inclusiveItems": [
      "Backstage access",
      "Complimentary gift bag",
      "Priority seating"
    ],
    "status": "ACTIVE",
    "createdAt": "2025-02-18T10:30:45+03:00",
    "updatedAt": "2025-02-18T11:00:00+03:00",
    "createdBy": "john_organizer",
    "updatedBy": "john_organizer"
  }
}

Success Response Fields: Same as Create Ticket response fields.

Possible Error Responses:

Status Scenario
404 Event not found or ticket not found

5. Update Ticket Capacity

Purpose: Updates the total quantity (capacity) of a ticket. This is the only capacity-related change permitted after an event is published. The new capacity must be greater than or equal to the number of tickets already sold.

Endpoint: PATCH {base_url}/{eventId}/{ticketId}/capacity

Access Level: 🔒 Protected (Event organizer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event Must be a valid UUID
ticketId UUID Yes The ticket to update capacity for Must be a valid UUID

Request Body Parameters:

Parameter Type Required Description Validation
newTotalQuantity integer Yes The new total capacity Min: 1, Max: 1,000,000. Must be ≥ ticketsSold

Request JSON Sample:

{
  "newTotalQuantity": 300
}

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket capacity updated successfully",
  "action_time": "2025-02-18T12:00:00",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventId": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
    "name": "VIP Pass",
    "price": 150.00,
    "ticketPricingType": "PAID",
    "totalTickets": 300,
    "ticketsSold": 200,
    "ticketsRemaining": 100,
    "ticketsAvailable": 100,
    "isSoldOut": false,
    "status": "ACTIVE",
    "createdAt": "2025-02-18T10:30:45+03:00",
    "updatedAt": "2025-02-18T12:00:00+03:00",
    "createdBy": "john_organizer",
    "updatedBy": "john_organizer"
  }
}

Note: If a ticket was previously SOLD_OUT and the new capacity exceeds tickets sold, the status is automatically reset to ACTIVE.

Possible Error Responses:

Status Scenario
401 No or expired token
403 Not the event organizer
404 Ticket not found
400 New capacity is less than the number of tickets already sold
422 newTotalQuantity is missing or below minimum

Capacity Below Sold Count (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot reduce capacity to 100 because 200 tickets have already been sold",
  "action_time": "2025-02-18T12:00:00",
  "data": "Cannot reduce capacity to 100 because 200 tickets have already been sold"
}

6. Update Ticket Status

Purpose: Manually changes the status of a ticket type. Use this to pause sales (INACTIVE), permanently stop sales (CLOSED), or reactivate a paused ticket (ACTIVE). The system automatically manages SOLD_OUT status — it cannot be set manually.

Endpoint: PATCH {base_url}/{eventId}/{ticketId}/status

Access Level: 🔒 Protected (Event organizer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event Must be a valid UUID
ticketId UUID Yes The ticket to update status for Must be a valid UUID

Request Body Parameters:

Parameter Type Required Description Validation
status string Yes The new status to set Enum: ACTIVE, INACTIVE, CLOSED. Cannot set SOLD_OUT or DELETED manually

Status Transition Rules:

Current Status Allowed Transitions Notes
ACTIVE INACTIVE, CLOSED Normal operations
INACTIVE ACTIVE, CLOSED Can be reactivated
SOLD_OUT ACTIVE, CLOSED ACTIVE only if capacity was increased first
CLOSED None Permanent. Cannot be changed
DELETED None Permanent. Cannot be changed

Request JSON Sample:

{
  "status": "INACTIVE"
}

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket status updated successfully",
  "action_time": "2025-02-18T13:00:00",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "VIP Pass",
    "status": "INACTIVE",
    "isOnSale": false,
    "updatedAt": "2025-02-18T13:00:00+03:00",
    "updatedBy": "john_organizer"
  }
}

Possible Error Responses:

Status Scenario
401 No or expired token
403 Not the event organizer
404 Ticket not found
400 Attempted to set SOLD_OUT or DELETED manually
400 Attempted to change status of a CLOSED or DELETED ticket
422 status field is missing

Attempt to Set SOLD_OUT (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot manually set status to SOLD_OUT. This status is automatically set when tickets are sold out.",
  "action_time": "2025-02-18T13:00:00",
  "data": "Cannot manually set status to SOLD_OUT. This status is automatically set when tickets are sold out."
}

Attempt to Change CLOSED Ticket (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot change status of closed ticket. Closed status is permanent.",
  "action_time": "2025-02-18T13:00:00",
  "data": "Cannot change status of closed ticket. Closed status is permanent."
}

7. Delete Ticket

Purpose: Soft-deletes a ticket type. The ticket is marked as deleted and hidden from all listings. Deletion is only allowed if zero tickets have been sold. If tickets have already been sold, close the ticket using the status endpoint instead.

Endpoint: DELETE {base_url}/{eventId}/{ticketId}

Access Level: 🔒 Protected (Event organizer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>

Path Parameters:

Parameter Type Required Description Validation
eventId UUID Yes The event Must be a valid UUID
ticketId UUID Yes The ticket to delete Must be a valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket deleted successfully",
  "action_time": "2025-02-18T14:00:00",
  "data": null
}

Possible Error Responses:

Status Scenario
401 No or expired token
403 Not the event organizer
404 Ticket not found
400 Ticket cannot be deleted because tickets have already been sold

Tickets Already Sold (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot delete ticket 'VIP Pass' because 45 tickets have been sold. You can close the ticket instead to stop sales.",
  "action_time": "2025-02-18T14:00:00",
  "data": "Cannot delete ticket 'VIP Pass' because 45 tickets have been sold. You can close the ticket instead to stop sales."
}

Quick Reference

Endpoint Summary

# Method Path Description Auth
1 POST /{eventId} Create a ticket type 🔒 Organizer
2 PUT /{ticketId} Update ticket details 🔒 Organizer
3 GET /{eventId} Get all tickets for an event 🌐 Public
4 GET /{eventId}/{ticketId} Get a single ticket by ID 🌐 Public
5 PATCH /{eventId}/{ticketId}/capacity Update ticket capacity 🔒 Organizer
6 PATCH /{eventId}/{ticketId}/status Update ticket status 🔒 Organizer
7 DELETE /{eventId}/{ticketId} Delete a ticket 🔒 Organizer

Common HTTP Status Codes

Code Meaning
200 OK Successful GET, PATCH, or DELETE
201 Created Successful POST (ticket created)
400 Bad Request Business rule violated (e.g. not DRAFT, already sold, duplicate name)
401 Unauthorized Missing or invalid token
403 Forbidden Authenticated but not the event organizer
404 Not Found Event or ticket does not exist
422 Unprocessable Entity Validation errors on request fields

Business Rule Cheat Sheet

Rule Detail
Create/Update Event must be in DRAFT status
Capacity Update Works on DRAFT and PUBLISHED events
Status Update Works on DRAFT and PUBLISHED events
FREE ticket Price must be exactly 0.00
PAID ticket Price must be greater than 0.00
DONATION ticket ONLINE_ONLY channel only. Max 1 per order and per user. No fixed price — buyer sets amount at checkout. price is null in response
Sales window Must fall within the event's registration window (registrationOpensAt to registrationClosesAt)
Sales period gap Minimum 30 minutes between salesStartDateTime and salesEndDateTime
HYBRID event Must have ≥ 1 IN_PERSON ticket and ≥ 1 ONLINE ticket to publish
Delete Only allowed if ticketsSold = 0
SOLD_OUT System-managed. Cannot be set manually. Auto-cleared when capacity is increased
CLOSED Permanent. Cannot be reversed
Back to top