Ticket Management API

Ticket Management API Documentation

Author: Josh,Josh S. Sakweli, Backend Lead Backend Team
Last Updated: 2025-12-1102-18
Version: v1.0

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

Short Description: The Ticket Management API provides comprehensive functionality for creating and managing ticket types for events in the Nexgate platform. This API enablesallows event organizers to define and manage ticket types for their events on NextGate. Organizers can create multiple ticket tiers (e.g. VIP, Early Bird, Student,General etc.)Admission), with flexiblecontrol pricing, capacity management,capacity, sales periods, purchase limits,visibility, and attendancesales modes for hybrid events.channels. Tickets canare onlyalways bescoped createdto fora specific event and follow the event's lifecycle from DRAFT events, with automatic validationthrough to ensure events meet ticketing requirements before publishing.PUBLISHED.

Hints:

• DRAFT Events Only: Tickets can only be created/addedcreated toand eventsfully edited while the event is in DRAFT status. Once published, only capacity and status changes are allowed.
• For MinimumHYBRID Ticketevents, Requirement:you Eventsmust needcreate at least 1one ACTIVEIN_PERSON ticket toand one ONLINE ticket before the event can be publishedpublished.
• Hybrid Event Requirement: HYBRID events need at least 1 IN_PERSON and 1 ONLINE ticket
• Unique Constraint: Ticket name + attendance modenames must be unique per event per attendance mode — you cannot have two IN_PERSON tickets both named "VIP Pass" on the same event.
• Capacity ProtectionDONATION: Cannot reduce capacity below tickets alreadyare soldrestricted to ONLINE_ONLY sales channel and a maximum of 1 ticket per order and per user.
• DeleteSoft Protection:deletion Canis used — a ticket can only deletebe deleted if zero tickets withhave zerobeen salessold. (otherwiseOtherwise, mustclose CLOSE)it using the status endpoint.
• AutomaticAll TICKETS Stage: Creating first ticket marks TICKETS stage as complete
• Status Transitions: CLOSED is permanent, SOLD_OUT is automatic, DELETED requires endpoint
• Sales Period: Ticketsdatetimes must be soldin 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. This is a user-facing journey — not a backend flow.

  [Organizer creates event in DRAFT status]
                    |
                    | (Event must be DRAFT before eventany startsticket 
Purchasework)
                    Limits:v
  Min/max. per. order,. max. per. user
. 
. . . . . . . . . . . . . . . . .
  .                                             .
  .   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 Validity:(name, Defineprice, whenetc.)  .
  .                                             .
  .   Wrong capacity?                           .
  .      --> Update Ticket Capacity             .
  .                                             .
  .   Ticket no longer needed?                  .
  .      --> Delete Ticket (only if 0 sold)     .
  .                                             .
  . . . . . . . . . . . . . . . . . . . . . . .
                    |
                    v
  [Event published — tickets expirego (beforelive event,for atbuyers]
                    event|
                    end,v
  or. custom)
. . . . . . . . . . . . . . . . . . . . . .
  .                                             .
  .   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            .
  .                                             .
  . . . . . . . . . . . . . . . . . . . . . . .

---

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:structure:

Success Response Structure

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

Error Response Structure

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

---

Standard

HTTP Method Badge Standards

• GET - GET - Green (Read operations)
• POST - POST - Blue (Create operations)
• PATCH - PATCH - Orange (Partial update operations)
• DELETE - DELETE - Red (Delete operations)

---

TicketResponse Structure

This is the comprehensive response structure returned by ticket endpoints:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "eventId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Early Bird VIP",
  "description": "VIP access with early bird discount - includes backstage pass, premium seating, and meet & greet",
  "price": 150.00,
  "totalTickets": 100,
  "ticketsSold": 75,
  "ticketsRemaining": 25,
  "ticketsAvailable": 25,
  "isSoldOut": false,
  "salesStartDateTime": "2025-11-01T00:00:00+03:00",
  "salesEndDateTime": "2025-12-14T23:59:59+03:00",
  "isOnSale": true,
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 5,
  "maxQuantityPerUser": 10,
  "checkInValidUntil": "EVENT_END",
  "customCheckInDate": null,
  "attendanceMode": "IN_PERSON",
  "inclusiveItems": [
    "Backstage pass",
    "Premium seating",
    "Meet & greet with artists",
    "Event merchandise pack",
    "Complimentary refreshments"
  ],
  "isHidden": false,
  "status": "ACTIVE",
  "createdAt": "2025-11-01T10:30:45+03:00",
  "updatedAt": "2025-12-01T14:20:30+03:00",
  "createdBy": "johndoe",
  "updatedBy": "johndoe"
}

Response Field DescriptionsFields

onsuccess;errordetailon

Field	Type	Description
idsuccess	string (UUID)boolean	Uniquetrue ticketfor identifiersuccessful operations, false for errors
eventIdhttpStatus	string (UUID)	EventHTTP thisstatus ticketname belongs(OK, toBAD_REQUEST, NOT_FOUND, etc.)
namemessage	string	TicketHuman-readable typedescription nameof (2-100the chars)operation result
description	string	Ticket description (max 500 chars)
price	decimal	Ticket price (can be 0.00 for free tickets)
totalTickets	integer	Total capacity/quantity available
ticketsSold	integer	Number of tickets sold
ticketsRemaining	integer	Calculated: totalTickets - ticketsSold
ticketsAvailable	integer	Currently available for purchase (same as ticketsRemaining)
isSoldOut	boolean	Whether all tickets are sold (ticketsSold >= totalTickets)
salesStartDateTime	string	When ticket sales begin (ISO 8601, optional)
salesEndDateTime	string	When ticket sales end (ISO 8601, optional)
isOnSale	boolean	Calculated: currently available for purchase based on status, dates, sold out
minQuantityPerOrder	integer	Minimum tickets per purchase (default: 1)
maxQuantityPerOrder	integer	Maximum tickets per purchase (optional, null = no limit)
maxQuantityPerUser	integer	Maximum tickets per user total (optional, null = no limit)
checkInValidUntil	enum	When ticket expires: BEFORE_EVENT_START, EVENT_END, CUSTOM
customCheckInDate	string	Custom expiry date (required if checkInValidUntil=CUSTOM)
attendanceMode	enum	IN_PERSON or ONLINE (required for HYBRID events)
inclusiveItems	array	List of items/perks included with ticket (max 50 items)
isHidden	boolean	Whether ticket is hidden (invite-only)
status	enum	Ticket status: ACTIVE, INACTIVE, CLOSED, SOLD_OUT, DELETED
createdAtaction_time	string	ISO 8601 timestamp of when the response was generated
updatedAtdata	object/string	ISOResponse 8601payload timestamp
createdBy	string	Username of ticket creator
updatedBy	string	Username of last updaterfailure

---

TicketSummaryResponseHTTP StructureMethod Badges

Lightweight

response
• 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. Buyer sets their own amount. Restricted to ONLINE_ONLY channel, max 1 per order and per user

SalesChannel

Value	Description
EVERYWHERE	Available both online and at the door
ONLINE_ONLY	Available for listpurchase views: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

"id":VIP","price":150.00,"totalTickets":false,"attendanceMode":"IN_PERSON","status":

Value	Description
{VISIBLE	Always "550e8400-e29b-41d4-a716-446655440000",shown "name":to "Earlythe Birdpublic
HIDDEN	Never 100,shown "ticketsSold":to 75,buyers "ticketsAvailable":(organizer 25,use "isSoldOut":only)
HIDDEN_WHEN_NOT_ON_SALE	Only "ACTIVE",visible "isOnSale":while truethe }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

---

Endpoints

---

1. Create Ticket

Purpose: CreateCreates a new ticket type for ana specific event. The event (onlymust forbe in DRAFT events)status. The authenticated user must be the event organizer.

Endpoint: POST {base_url}/e-events/tickets/{eventId}

Access Level: 🔒 Protected (Requires Bearer Token + Event Organizer)organizer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token (format: Bearer <token>)
Content-Type	string	Yes	Must be application/json

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	string (UUID)UUID	Yes	UUID ofThe event to createadd the ticket forto	Must be a valid UUID

Request JSON Sample (Hybrid Event - In-Person Ticket):

{
  "name": "Early Bird VIP",
  "description": "VIP access with early bird discount - includes backstage pass, premium seating, and meet & greet",
  "price": 150.00,
  "totalQuantity": 100,
  "salesStartDateTime": "2025-11-01T00:00:00+03:00",
  "salesEndDateTime": "2025-12-14T23:59:59+03:00",
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 5,
  "maxQuantityPerUser": 10,
  "checkInValidUntil": "EVENT_END",
  "attendanceMode": "IN_PERSON",
  "inclusiveItems": [
    "Backstage pass",
    "Premium seating",
    "Meet & greet with artists",
    "Event merchandise pack",
    "Complimentary refreshments"
  ],
  "isHidden": false
}

Request Body Parameters:

Basic Information

Parameter	Type	Required	Description	Validation
name	string	Yes	Ticket typename name(e.g. "VIP Pass", "Early Bird")	Min: 2, Max: 100 characterscharacters. Must be unique per event per attendance mode
description	string	No	TicketOptional description of what the ticket includes	Max: 500 characters
price	decimal	Yes	Ticket priceprice. (TZS)Use 0.00 for FREE tickets	Min: 0.00,00. MaxMax: 8 digitsinteger +digits, 2 decimalsdecimal places. FREE → must be 0.00. PAID → must be > 0.00

Capacity Management

model

Parameter	ticketPricingType	Type	string	Required	Yes	Description	Pricing	Validation	Enum: PAID, FREE, DONATION
salesChannel	string	Yes	Where the ticket can be purchased	Enum: EVERYWHERE, ONLINE_ONLY, AT_DOOR_ONLY. Defaults to EVERYWHERE
totalQuantity	integer	Yes	Total number of tickets available	Min: 1, Max: 1,000,000

Sales Period (Optional)

aftersalesStartDateTime

Parameter	Type	Required	Description	Validation
salesStartDateTime	stringdatetime	No	When sales open. If omitted, sales begin immediately	ISO 8601,8601 cannotZonedDateTime. Cannot be after event start
salesEndDateTime	stringdatetime	No	When sales endclose	ISO 8601,8601 ZonedDateTime. Must be after salesStartDateTime. Cannot be after event start
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	Min: 1, Max: 100. Must be before≥ minQuantityPerOrder. Leave null for no limit
maxQuantityPerUser	integer	No	Maximum tickets a single user can purchase across all orders	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 start,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

Purchase

Request Limits

JSON Sample:

{
  "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": "2025-06-01T08:00:00+03:00",
  "salesEndDateTime": "2025-08-09T23:59:00+03:00",
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 4,
  "maxQuantityPerUser": 4,
  "visibility": "VISIBLE",
  "attendanceMode": "IN_PERSON",
  "inclusiveItems": [
    "Backstage access",
    "Complimentary gift bag",
    "Priority seating"
  ]
}

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": "2025-06-01T08:00:00+03:00",
    "salesEndDateTime": "2025-08-09T23:59:00+03:00",
    "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
  }
}

Success Response Fields:

UniqueidentifierticketTheeventbelongs Max:1000,mustbe

Parameter	Type	RequiredField	Description	Validation
minQuantityPerOrderid	integer	No	Minfor perthis purchase	Min: 1, Default: 1type
maxQuantityPerOrdereventId	integer	No	Maxthis perticket purchase	Min: 1, Max: 100, must be >= minQuantityPerOrderto
maxQuantityPerUsername	integerTicket name
description	NoTicket description
price	MaxTicket price
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 totalacross all orders (null = no limit)
visibility	Min:Visibility 1,setting
visibilityStartDate	Start >=of maxQuantityPerOrdercustom 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

Ticket

Possible Validity

Error Responses:

ParameterStatus	Type	Required	Description	ValidationScenario
checkInValidUntil	enum401	No	Whenor ticketexpired expires	BEFORE_EVENT_START, EVENT_END (default), CUSTOMtoken
customCheckInDate403	stringAuthenticated user is not the event organizer
404	ConditionalEvent not found
400	CustomEvent expiryis datenot in DRAFT status
400	RequiredTicket ifname checkInValidUntil=CUSTOM,already ISOexists 8601for this event and attendance mode
422	Validation errors (missing required fields, invalid price, quantity issues, etc.)

For Hybrid Events

Parameter	Type	Required	Description	Validation
attendanceMode	enum	Conditional	Attendance type	IN_PERSON or ONLINE (required for HYBRID events)

Additional Features

Parameter	Type	Required	Description	Validation
inclusiveItems	array	No	Included perks/items	Max 50 items, each max 200 chars
isHidden	boolean	No	Invite-only ticket	Default: false

Success Response: Returns complete TicketResponse structure

Success Response Message: "Ticket created successfully"

HTTP Status Code: 201 CREATED

Behavior:

• Event must be in DRAFT status
• Ticket name + attendanceMode must be unique per event
• First ticket creation marks TICKETS stage as complete
• Sets currentStage to REVIEW if TICKETS was current stage
• HYBRID events require attendanceMode (IN_PERSON or ONLINE)
• Sales period must be before event starts
• Initial status set to ACTIVE
• Initial quantitySold set to 0

Standard Error Types:

• 400 BAD_REQUEST: Event not in DRAFT status, duplicate ticket name, validation errors
• 401 UNAUTHORIZED: Authentication issues
• 403 FORBIDDEN: Not event organizer
• 404 NOT_FOUND: Event not found
• 422 UNPROCESSABLE_ENTITY: Validation errors
• 500 INTERNAL_SERVER_ERROR: Server errors

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-12-11T10: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-12-11T10:02-18T10:30:45",
  "data": "A ticket with name 'VIP Pass' and attendance mode 'IN_PERSON' already exists for this event"
}

MissingValidation Attendance Mode for HybridError (400)422):

{
  "success": false,
  "httpStatus": "BAD_REQUEST"UNPROCESSABLE_ENTITY",
  "message": "AttendanceValidation mode (IN_PERSON or ONLINE) is required for HYBRID events"failed",
  "action_time": "2025-12-11T10:02-18T10:30:45",
  "data": {
    "Attendancename": mode"Ticket (IN_PERSON or ONLINE)name is required for HYBRID events"
}

Sales End After Event Start (400):

{required",
    "success": false,
  "httpStatus"price": "BAD_REQUEST",
  "message": "Sales end date cannot be after event start date. TicketsPrice must be soldzero beforeor the event begins."positive",
    "action_time"ticketPricingType": "2025-12-11T10:30:45",Ticket "data":type "Salesis end date cannot be after event start date. Tickets must be sold before the event begins."required"
  }

Invalid Purchase Limits (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Maximum quantity per order (3) must be greater than or equal to minimum (5)",
  "action_time": "2025-12-11T10:30:45",
  "data": "Maximum quantity per order (3) must be greater than or equal to minimum (5)"
}

---

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	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	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	ISO 8601 ZonedDateTime
salesEndDateTime	datetime	No	Updated sales close time	ISO 8601 ZonedDateTime. Must be after salesStartDateTime and before event start
minQuantityPerOrder	integer	No	Updated minimum per order	Min: 1
maxQuantityPerOrder	integer	No	Updated maximum per order	Min: 1, Max: 100
maxQuantityPerUser	integer	No	Updated maximum per user	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": "2025-06-01T08:00:00+03:00",
    "salesEndDateTime": "2025-08-09T23:59:00+03:00",
    "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, etc.)

---

3. Get All Tickets byfor Event

Purpose: RetrieveRetrieves a lightweight summary list of all ticketactive types(non-deleted) tickets for ana eventgiven event, ordered by creation date ascending. This is the primary endpoint for displaying ticket listings to buyers or organizers.

Endpoint: GET {base_url}/e-events/tickets/{eventId}

Access Level: 🔓🌐 Public (Anyone can view tickets for public events)

Authentication: BearerNone Token (optional for public events)required

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	string (UUID)UUID	Yes	UUID ofThe event to retrieve tickets for	Must be a valid UUID

Success Response: Returns array of TicketSummaryResponse objects

Success Response Message: "Tickets retrieved successfully"

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Tickets retrieved successfully",
  "action_time": "2025-12-11T10:02-18T10:30:45",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "EarlyGeneral Bird VIP"Admission",
      "price": 150.25.00,
      "ticketPricingType": "PAID",
      "salesChannel": "EVERYWHERE",
      "visibility": "VISIBLE",
      "totalTickets": 100,1000,
      "ticketsSold": 75,342,
      "ticketsAvailable": 25,658,
      "isSoldOut": false,
      "attendanceMode": "IN_PERSON",
      "status": "ACTIVE",
      "isOnSale": true
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001"b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Regular"VIP Pass",
      "price": 50.150.00,
      "ticketPricingType": "PAID",
      "salesChannel": "EVERYWHERE",
      "visibility": "VISIBLE",
      "totalTickets": 500,200,
      "ticketsSold": 320,200,
      "ticketsAvailable": 180,0,
      "isSoldOut": false,true,
      "attendanceMode": "IN_PERSON",
      "status": "ACTIVE"SOLD_OUT",
      "isOnSale": truefalse
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002"c3d4e5f6-a7b8-9012-cdef-012345678902",
      "name": "VirtualOnline Pass"Stream Access",
      "price": 25.10.00,
      "ticketPricingType": "PAID",
      "salesChannel": "ONLINE_ONLY",
      "visibility": "VISIBLE",
      "totalTickets": 1000,5000,
      "ticketsSold": 850,1230,
      "ticketsAvailable": 150,3770,
      "isSoldOut": false,
      "attendanceMode": "ONLINE",
      "status": "ACTIVE",
      "isOnSale": true
    }
  ]
}

BehaviorSuccess Response Fields (per item):

Field	Description
id	Unique identifier for the ticket type
name	Ticket name
price	Ticket price
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:

• Returns
onlynon-deletedtickets
• Sorted
bycreationdate(oldest first)
• Includes tickets in all statuses (ACTIVE, INACTIVE, CLOSED, SOLD_OUT)
• Hidden tickets (isHidden=true) are included

Standard Error Types:

NOT_FOUND:

Status	Scenario
404	Event not found

---

3.4. Get Ticket by ID

Purpose: RetrieveRetrieves detailedthe informationfull fordetails of a single ticket type by its ID. Returns all fields including audit info, calculated quantities, and visibility state.

Endpoint: GET {base_url}/e-events/tickets/{eventId}/{ticketId}

Access Level: 🔓🌐 Public

Authentication: BearerNone Token (optional)required

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	string (UUID)UUID	Yes	UUID ofThe event (forthe URLticket consistency)belongs to	Must be a valid UUID
ticketId	string (UUID)UUID	Yes	UUIDThe ofspecific ticket to retrieve	Must be a valid UUID

Success Response JSON Sample: Returns complete TicketResponse structure with all details

Success

{
  Response"success": Messagetrue,
  "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": "2025-06-01T08:00:00+03:00",
    "salesEndDateTime": "2025-08-09T23:59:00+03:00",
    "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.

StandardPossible Error TypesResponses:

NOT_FOUND: Ticket

Status	Scenario
404	Event not found or ticket not found

---

4.5. Update Ticket Capacity

Purpose: UpdateUpdates the total ticketquantity quantity/(capacity) of a ticket. This is the only capacity-related change permitted after an event is published. Useful when you need to release more tickets or correct an initial quantity. The new capacity must be greater than or equal to the number of tickets already sold.

Endpoint: PATCH {base_url}/e-events/tickets/{eventId}/{ticketId}/capacity

Access Level: 🔒 Protected (Event Organizerorganizer Only)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	string (UUID)UUID	Yes	UUID ofThe event	Must be a valid UUID
ticketId	string (UUID)UUID	Yes	UUID ofThe ticket to update capacity for	Must be a valid UUID

Request JSON Sample:

{
  "newTotalQuantity": 150
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
newTotalQuantity	integer	Yes	NewThe new total capacity	Min: 1, Max: 1,000,000,000. mustMust be >=≥ ticketsSold

SuccessRequest ResponseJSON Sample:

Returns

{
  updated"newTotalQuantity": TicketResponse
300
}

Success Response MessageJSON 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",
    "description": "Full weekend access with backstage entry and a complimentary gift bag.",
    "price": 150.00,
    "ticketPricingType": "PAID",
    "salesChannel": "EVERYWHERE",
    "totalTickets": 300,
    "ticketsSold": 200,
    "ticketsRemaining": 100,
    "ticketsAvailable": 100,
    "isSoldOut": false,
    "salesStartDateTime": "2025-06-01T08:00:00+03:00",
    "salesEndDateTime": "2025-08-09T23:59:00+03:00",
    "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-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.

Success Response Fields: Same as Create Ticket response fields.

BehaviorPossible Error Responses:

• Can
updatecapacityforbothDRAFTandPUBLISHEDevents
• If
ticketwasSOLD_OUTcount)
• Reopen
Sold Out Tickets: Increase capacity to resume sales

Standard Error Types:

• 400 BAD_REQUEST: New capacity below tickets sold
• 403 FORBIDDEN: Not event organizer
• 404 NOT_FOUND: Ticket not found

Status	Scenario
401	No or expired token
403	Not the event organizer
404	Ticket not found
400	New capacity mustis beless >=than the number of tickets already sold
422	newTotalQuantity andis newmissing capacity > ticketsSold, status changes to ACTIVE Works for all event statuses (DRAFT, PUBLISHED, HAPPENING, etc.) Use Cases: Increase Capacity: Venue size increased, add more tickets Decrease Capacity: Venue size reduced (if notor below soldminimum

Error Response ExamplesExample:

Capacity Below Sold Count (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot reduce capacity to 50100 because 75200 tickets have already been sold",
  "action_time": "2025-12-11T10:30:45"02-18T12:00:00",
  "data": "Cannot reduce capacity to 50100 because 75200 tickets have already been sold"
}

---

5.6. Update Ticket Status

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

Endpoint: PATCH {base_url}/e-events/tickets/{eventId}/{ticketId}/status

Access Level: 🔒 Protected (Event Organizerorganizer Only)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	string (UUID)UUID	Yes	UUID ofThe event	Must be a valid UUID
ticketId	string (UUID)UUID	Yes	UUID ofThe 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"
}

RequestSuccess BodyResponse ParametersJSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Ticket status updated successfully",
  "action_time": "2025-02-18T13:00:00",
  "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": "2025-06-01T08:00:00+03:00",
    "salesEndDateTime": "2025-08-09T23:59:00+03:00",
    "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": "INACTIVE",
    "createdAt": "2025-02-18T10:30:45+03:00",
    "updatedAt": "2025-02-18T13:00:00+03:00",
    "createdBy": "john_organizer",
    "updatedBy": "john_organizer"
  }
}

Success Response Fields: Same as Create Ticket response fields.

Possible Error Responses:

ParameterStatus	Type	Required	Description	Valid ValuesScenario
status401	enumNo or expired token
403	YesNot the event organizer
404	NewTicket ticketnot statusfound
400	ACTIVE,Attempted INACTIVE,to set SOLD_OUT or DELETED manually
400	Attempted to change status of a CLOSED or DELETED ticket
422	status field is missing

Success Response: Returns updated TicketResponse

Success Response Message: "Ticket status updated successfully"

Status Transition Rules:

From Status	To Status	Allowed?	Notes
ACTIVE	INACTIVE	✅ Yes	Temporarily stop sales
ACTIVE	CLOSED	✅ Yes	Permanently stop sales
INACTIVE	ACTIVE	✅ Yes	Resume sales
INACTIVE	CLOSED	✅ Yes	Permanently stop sales
CLOSED	ANY	❌ No	CLOSED is permanent
SOLD_OUT	ACTIVE	✅ Yes	Only if capacity increased
SOLD_OUT	CLOSED	✅ Yes	Permanently close
SOLD_OUT	INACTIVE	❌ No	Invalid transition
DELETED	ANY	❌ No	Cannot change deleted tickets
ANY	SOLD_OUT	❌ No	Automatic status only
ANY	DELETED	❌ No	Use delete endpoint

Use Cases:

• ACTIVE → INACTIVE: Temporarily pause sales (during review, pricing adjustment)
• INACTIVE → ACTIVE: Resume sales after pause
• ACTIVE/INACTIVE → CLOSED: Permanently stop sales (event capacity changed, tier removed)
• SOLD_OUT → ACTIVE: Resume sales after capacity increase (requires capacity update first)

Standard Error Types:

• 400 BAD_REQUEST: Invalid status transition
• 403 FORBIDDEN: Not event organizer
• 404 NOT_FOUND: Ticket not found

Error Response Examples:

InvalidAttempt Transition - CLOSED is Permanent (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot change status of closed ticket. Closed status is permanent.",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot change status of closed ticket. Closed status is permanent."
}

Cannot Manuallyto 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-12-11T10:30:45"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."
}

---

6.7. Delete Ticket

Purpose: Soft deleteSoft-deletes a ticket typetype. (The ticket is marked as deleted and hidden from all listings but is not physically removed from the system. Deletion is only allowed if nozero tickets sold)have been sold. If tickets have already been sold, close the ticket instead using the status endpoint.

Endpoint: DELETE {base_url}/e-events/tickets/{eventId}/{ticketId}

Access Level: 🔒 Protected (Event Organizerorganizer Only)only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	string (UUID)UUID	Yes	UUID ofThe event	Must be a valid UUID
ticketId	string (UUID)UUID	Yes	UUID ofThe ticket to delete	Must be a valid UUID

Success Response Message: "Ticket deleted successfully"

Success Response JSON Sample:

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

BehaviorPossible Error Responses:

• Soft
delete(setsisDeleted=true,status=DELETED)
• Can
onlydeleteifquantitySold mustusestatus update to CLOSE instead
• Sets deletedAt timestamp and deletedBy user
• Deleted tickets excluded from GET lists

Standard Error Types:

• 400 BAD_REQUEST: Cannot delete ticket with sales
• 403 FORBIDDEN: Not event organizer
• 404 NOT_FOUND: Ticket not found

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

Error Response Example:

CannotTickets DeleteAlready Ticket with SalesSold (400):

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

---

TicketQuick Status LifecycleReference

StatusEndpoint Flow Diagram

ACTIVE ⇄ INACTIVE → CLOSED (permanent)
   ↓
SOLD_OUT → ACTIVE (if capacity increased)
   ↓
DELETED (if no sales)

Status DescriptionsSummary

Status#	Method	Path	Description	Can Edit?	Can Delete?	Available for Purchase?Auth
ACTIVE1	Normal selling statusPOST	Yes/{eventId}	YesCreate (ifa noticket sales)type	Yes🔒 (if within sales period)Organizer
INACTIVE2	Temporarily pausedPUT	Yes/{ticketId}	YesUpdate (ifticket no sales)details	No🔒 Organizer
CLOSED3	Permanently stoppedGET	No/{eventId}	NoGet all tickets for an event	No🌐 Public
SOLD_OUT4	All tickets soldGET	Capacity only/{eventId}/{ticketId}	NoGet a single ticket by ID	No🌐 Public
DELETED5	Soft deletedPATCH	No/{eventId}/{ticketId}/capacity	N/AUpdate ticket capacity	No🔒 Organizer
6	PATCH	/{eventId}/{ticketId}/status	Update ticket status	🔒 Organizer
7	DELETE	/{eventId}/{ticketId}	Delete a ticket	🔒 Organizer

Automatic Status Changes

• SOLD_OUT: Automatically set when ticketsSold >= totalTickets
• ACTIVE: Automatically set when capacity increased on SOLD_OUT ticket

---

Ticket Types & Use Cases

Common Ticket Types

1. Early Bird

{
  "name": "Early Bird",
  "price": 50.00,
  "totalQuantity": 100,
  "salesEndDateTime": "2025-11-30T23:59:59+03:00",
  "maxQuantityPerOrder": 5
}

• Limited quantity
• Sales end date before regular tickets
• Discounted price

2. VIP/Premium

{
  "name": "VIP Pass",
  "price": 200.00,
  "totalQuantity": 50,
  "inclusiveItems": [
    "Backstage access",
    "Premium seating",
    "Meet & greet",
    "Gift bag"
  ],
  "checkInValidUntil": "CUSTOM",
  "customCheckInDate": "2025-12-18T00:00:00+03:00"
}

• Higher price
• Limited quantity
• Multiple perks
• Extended validity (after-party access)

3. Student/Discount

{
  "name": "Student Discount",
  "price": 25.00,
  "totalQuantity": 200,
  "maxQuantityPerUser": 2,
  "isHidden": true
}

• Discounted price
• Per-user limit
• Hidden (requires special link/code)

4. Group Tickets

{
  "name": "Group Pass (5 people)",
  "price": 200.00,
  "totalQuantity": 50,
  "minQuantityPerOrder": 5,
  "maxQuantityPerOrder": 5
}

• Fixed quantity per purchase
• Bulk pricing

5. Hybrid Event - In-Person

{
  "name": "In-Person Pass",
  "price": 100.00,
  "totalQuantity": 300,
  "attendanceMode": "IN_PERSON",
  "inclusiveItems": [
    "Physical venue access",
    "Networking lunch",
    "Event materials"
  ]
}

• Physical venue access
• Higher price than online

6. Hybrid Event - Online

{
  "name": "Virtual Pass",
  "price": 50.00,
  "totalQuantity": 1000,
  "attendanceMode": "ONLINE",
  "inclusiveItems": [
    "Live stream access",
    "Recording access (30 days)",
    "Digital materials"
  ]
}

• Virtual access
• Higher capacity
• Lower price

---

Ticket Validity Types

BEFORE_EVENT_START

Ticket expires just before event begins.

Use Cases:

• Early bird tickets that expire at event time
• Tickets that don't grant event entry (pre-event workshops)

Behavior:

• Cannot check in once event starts
• Useful for time-limited promotional tickets

EVENT_END (Default)

Ticket valid until event ends.

Use Cases:

• Standard event tickets
• Multi-day pass valid for all days

Behavior:

• Can check in anytime during event
• For multi-day events, valid until last day ends
• Most common validity type

CUSTOM

Ticket valid until specific custom date/time.

Use Cases:

• VIP after-party access extending beyond event
• Early access tickets (valid before event starts)
• Extended access (recordings, venue access)

Behavior:

• Requires customCheckInDate field
• Flexible validity period
• Can extend before or after event dates

Example (VIP with After-Party):

{
  "checkInValidUntil": "CUSTOM",
  "customCheckInDate": "2025-12-18T02:00:00+03:00"
}

Event ends Dec 17 at 23:00, but VIP ticket valid until Dec 18 at 02:00 (after-party).

---

Purchase Limits Explained

minQuantityPerOrder

Minimum tickets required per purchase.

Default: 1

Use Cases:

• minQuantityPerOrder: 2 - Couples/pairs only
• minQuantityPerOrder: 5 - Group bookings only
• minQuantityPerOrder: 1 - Standard (anyone can buy)

maxQuantityPerOrder

Maximum tickets per single purchase.

Default: null (no limit)

Use Cases:

• maxQuantityPerOrder: 5 - Prevent bulk buying
• maxQuantityPerOrder: 10 - Reasonable group size
• maxQuantityPerOrder: 2 - Limit resellers

maxQuantityPerUser

Maximum tickets per user across all purchases.

Default: null (no limit)

Use Cases:

• maxQuantityPerUser: 2 - Limit high-demand events
• maxQuantityPerUser: 10 - Fair distribution
• maxQuantityPerUser: 1 - One per person (exclusive events)

Validation Rules

• maxQuantityPerOrder must be >= minQuantityPerOrder
• maxQuantityPerUser must be >= maxQuantityPerOrder
• If only maxQuantityPerUser set, must be >= minQuantityPerOrder

Example Configurations:

Standard Ticket:

{
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 10,
  "maxQuantityPerUser": 20
}

Group Only:

{
  "minQuantityPerOrder": 5,
  "maxQuantityPerOrder": 5,
  "maxQuantityPerUser": 10
}

Limited Per Person:

{
  "minQuantityPerOrder": 1,
  "maxQuantityPerOrder": 2,
  "maxQuantityPerUser": 2
}

---

Sales Period Management

Sales Period Rules

• salesStartDateTime: Optional, defaults to ticket creation time
• salesEndDateTime: Optional, defaults to event start time
• Both must be before event starts
• End must be after start

Use Cases

1. Phased Sales

// Early Bird Phase
{
  "name": "Early Bird",
  "salesEndDateTime": "2025-11-30T23:59:59+03:00"
}

// Regular Phase
{
  "name": "Regular",
  "salesStartDateTime": "2025-12-01T00:00:00+03:00"
}

2. Time-Limited Flash Sale

{
  "name": "Flash Sale",
  "salesStartDateTime": "2025-12-01T12:00:00+03:00",
  "salesEndDateTime": "2025-12-01T18:00:00+03:00"
}

3. Last Minute Tickets

{
  "name": "Last Minute",
  "salesStartDateTime": "2025-12-14T00:00:00+03:00",
  "salesEndDateTime": "2025-12-14T23:59:59+03:00"
}

isOnSale Calculation

Ticket isOnSale = true when ALL conditions met:

1. status = ACTIVE
2. isDeleted = false
3. !isSoldOut (tickets available)
4. Current time >= salesStartDateTime (or null)
5. Current time <= salesEndDateTime (or null)

---

Hybrid Events - Attendance Modes

Requirements for HYBRID Events

• Must have at least 1 ACTIVE ticket with attendanceMode: IN_PERSON
• Must have at least 1 ACTIVE ticket with attendanceMode: ONLINE
• Cannot publish HYBRID event without both modes

Attendance Mode Rules

• Required: For HYBRID events only
• Optional: For IN_PERSON and ONLINE events (ignored if provided)
• Values: IN_PERSON or ONLINE
• Uniqueness: Name + AttendanceMode must be unique per event

Example: HYBRID Event Tickets

[
  {
    "name": "VIP Pass",
    "price": 200.00,
    "attendanceMode": "IN_PERSON",
    "totalQuantity": 50
  },
  {
    "name": "VIP Pass",
    "price": 100.00,
    "attendanceMode": "ONLINE",
    "totalQuantity": 200
  },
  {
    "name": "Regular",
    "price": 100.00,
    "attendanceMode": "IN_PERSON",
    "totalQuantity": 300
  },
  {
    "name": "Regular",
    "price": 50.00,
    "attendanceMode": "ONLINE",
    "totalQuantity": 1000
  }
]

Note: Same name "VIP Pass" allowed because attendance modes differ.

---

Inclusive Items

Purpose

List of perks, benefits, or items included with ticket purchase.

Rules

• Maximum 50 items per ticket
• Each item max 200 characters
• Cannot be null or empty strings
• Displayed to attendees during purchase

Use Cases

VIP Ticket:

{
  "inclusiveItems": [
    "Backstage pass",
    "Premium seating (front 3 rows)",
    "Meet & greet with performers",
    "Exclusive merchandise pack",
    "Complimentary beverages",
    "Access to VIP lounge",
    "Reserved parking"
  ]
}

Conference Ticket:

{
  "inclusiveItems": [
    "Access to all sessions",
    "Networking lunch (Day 1 & 2)",
    "Conference materials & notebook",
    "Certificate of attendance",
    "6 months digital content access"
  ]
}

Workshop Ticket:

{
  "inclusiveItems": [
    "4-hour hands-on workshop",
    "Toolkit & materials",
    "Digital resources library",
    "Follow-up Q&A session"
  ]
}

---

Event Publishing Requirements

Minimum Ticket Requirements

For IN_PERSON and ONLINE Events

• Minimum: 1 ACTIVE ticket
• Can have multiple ticket tiers (Early Bird, Regular, VIP)

For HYBRID Events

• Minimum: 1 ACTIVE IN_PERSON ticket
• Minimum: 1 ACTIVE ONLINE ticket
• Total minimum: 2 ACTIVE tickets (one of each mode)

Pre-Publish Validation

When attempting to publish an event, the system validates:

1. Ticket Existence: At least minimum required tickets exist
2. Ticket Status: Tickets are in ACTIVE status
3. Not Deleted: Tickets are not soft deleted
4. Attendance Modes: HYBRID events have both IN_PERSON and ONLINE

Example Error (HYBRID event missing ONLINE ticket):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "HYBRID events must have at least 1 active ONLINE ticket before publishing",
  "action_time": "2025-12-11T10:30:45",
  "data": "HYBRID events must have at least 1 active ONLINE ticket before publishing"
}

---

Quick Reference Guide

Common HTTP Status Codes

Ticket Validation errors, business Authentication Not
Ticket/event
Error:Servererror

Code	Meaning
200 OK:	Successful requestGET, PATCH, or DELETE
201 CREATEDCreated:	Successful createdPOST successfully(ticket created)
400 Bad Request:	Business rule violationsviolated (e.g. not DRAFT, already sold, duplicate name)
401 Unauthorized:	Missing required/failedor invalid token
403 Forbidden:	Authenticated but not the event organizer
404 Not Found:	Event or ticket does not foundexist
422 Unprocessable Entity:	Validation errors 500on Internalrequest Serverfields

DataBusiness FormatRule StandardsCheat Sheet

• Dates:
ISO8601withtimezone(2025-12-15T18:00:00+03:00)
• IDs:
UUIDformat
• Price: Decimal with 2 decimal places (150.00)
• Currency: TZS (Tanzanian Shilling)
• Quantity: Integer (positive numbers)

Ticket Creation Checklist

1. ✅
• ✅
Chooseunique(+Definesalesperiod
• ✅
validityitems(optional)
• ✅
attendance

Best

Practices

Pricing

• Group
tickets:minmaxrulesforeachfield
• 400 Draft Status:
• 400
DuplicateName:Use different name or attendance mode
• 400
soldcount

Rule	Detail
Create/Update	Event ismust be in DRAFT status
Capacity nameUpdate	Works attendanceon mode for HYBRID) ✅ Set priceDRAFT and quantity PUBLISHED ✅events
Status (optional)Update	Works Configureon purchaseDRAFT limitsand ✅PUBLISHED Setevents
FREE ticket	Price typemust ✅be Addexactly inclusive0.00
PAID Setticket	Price modemust (requiredbe forgreater HYBRID)than 0.00
DONATION Strategy: ticket	ONLINE_ONLY Earlychannel bird:only. 20-30% discount Regular: Standard price VIP: 2-3x regular price Student: 40-50% discount Capacity Planning: VIP/Premium: 10-15% of total Early Bird: 20-30% of total Regular: Remaining capacity Online (hybrid): 2-3x physical capacity Sales Periods: Early Bird: 1-2 months before event Regular: UntilMax 1 day before event Last Minute: Final 24-48 hours Purchase Limits: Standard events: max 10 per order High-demand events: max 2and per user
HYBRID 5,event	Must 5have per≥ order1 IN_PERSON Errorticket Handlingand Tips ≥ 1 422ONLINE Errors:ticket Checkto validationpublish
Delete	Only createallowed ticketsif forticketsSold DRAFT= events0
SOLD_OUT	System-managed. Cannot Delete:be Useset CLOSEmanually. statusAuto-cleared insteadwhen 400capacity Capacityis Error:increased
CLOSED	Permanent. Cannot reducebe belowreversed

Common Mistakes to Avoid

❌ Creating tickets for PUBLISHED events ❌ Missing attendance mode for HYBRID events ❌ Sales period after event start ❌ maxPerOrder < minPerOrder ❌ Trying to delete tickets with sales ❌ Manually setting SOLD_OUT status ❌ Changing CLOSED ticket status