openapi: 3.0.3
info:
  title: Eventzilla API
  description: >-
    The Eventzilla REST API provides access to event management operations
    including listing and retrieving events, managing ticket categories,
    processing registrations and orders, managing attendees, performing
    check-ins, and handling checkout workflows. Authentication is via an
    API key passed in the x-api-key request header.
  version: "2.0"
  contact:
    name: Eventzilla Support
    email: support@eventzilla.net
    url: https://community.eventzilla.net/
  termsOfService: https://www.eventzilla.net/terms-conditions/
  license:
    name: Proprietary
    url: https://www.eventzilla.net/terms-conditions/
externalDocs:
  description: Eventzilla API Documentation
  url: https://developer.eventzilla.net/docs/
servers:
  - url: https://www.eventzillaapi.net/api/v2
    description: Eventzilla API v2
security:
  - ApiKeyAuth: []
tags:
  - name: Categories
    description: Event category operations
  - name: Events
    description: Event listing and detail operations
  - name: Tickets
    description: Ticket type operations
  - name: Transactions
    description: Transaction and order operations
  - name: Attendees
    description: Attendee management and check-in operations
  - name: Users
    description: Organizer and sub-organizer operations
  - name: Checkout
    description: Checkout workflow operations
paths:
  /categories:
    get:
      operationId: listCategories
      summary: List event categories
      description: Retrieve all available event categories.
      tags:
        - Categories
      responses:
        "200":
          description: List of event categories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CategoriesResponse"
  /events:
    get:
      operationId: listEvents
      summary: List events
      description: List all events with optional filtering and pagination.
      tags:
        - Events
      parameters:
        - name: status
          in: query
          description: Filter by event status
          schema:
            type: string
            enum: [live, draft, unpublished, completed]
        - name: category
          in: query
          description: Filter by event category
          schema:
            type: string
        - name: offset
          in: query
          description: Number of records to skip
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum records per response
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated list of events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventsResponse"
  /events/{eventid}:
    get:
      operationId: getEvent
      summary: Get event by ID
      description: Retrieve details for a specific event.
      tags:
        - Events
      parameters:
        - name: eventid
          in: path
          required: true
          description: Unique identifier of the event
          schema:
            type: integer
      responses:
        "200":
          description: Event details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventsResponse"
  /events/{eventid}/tickets:
    get:
      operationId: listEventTickets
      summary: List ticket categories for event
      description: Retrieve all ticket types and donation options for a specific event.
      tags:
        - Tickets
      parameters:
        - name: eventid
          in: path
          required: true
          description: Unique identifier of the event
          schema:
            type: integer
      responses:
        "200":
          description: Ticket types and donation options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TicketsResponse"
  /events/{eventid}/transactions:
    get:
      operationId: listEventTransactions
      summary: List transactions for event
      description: Retrieve all transactions for a specific event with pagination.
      tags:
        - Transactions
      parameters:
        - name: eventid
          in: path
          required: true
          description: Unique identifier of the event
          schema:
            type: integer
        - name: offset
          in: query
          description: Number of records to skip
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum records per response
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated list of transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionsListResponse"
  /events/{eventid}/attendees:
    get:
      operationId: listEventAttendees
      summary: List attendees for event
      description: Retrieve all attendees for a specific event.
      tags:
        - Attendees
      parameters:
        - name: eventid
          in: path
          required: true
          description: Unique identifier of the event
          schema:
            type: integer
        - name: offset
          in: query
          description: Number of records to skip
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum records per response
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: List of attendees
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendeesListResponse"
  /events/togglesales:
    post:
      operationId: toggleEventSales
      summary: Toggle event sales
      description: Publish or unpublish an event to start or stop ticket sales.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ToggleSalesRequest"
      responses:
        "200":
          description: Updated event status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToggleSalesResponse"
  /events/order/confirm:
    post:
      operationId: confirmOrder
      summary: Confirm event order
      description: Confirm a pending order for an event.
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderConfirmRequest"
      responses:
        "200":
          description: Order confirmation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderConfirmResponse"
  /events/order/cancel:
    post:
      operationId: cancelOrder
      summary: Cancel event order
      description: Cancel an existing order for an event.
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCancelRequest"
      responses:
        "200":
          description: Order cancellation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderCancelResponse"
  /users/:
    get:
      operationId: listUsers
      summary: List users
      description: List all organizers and sub-organizers with pagination.
      tags:
        - Users
      parameters:
        - name: offset
          in: query
          description: Number of records to skip
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum records per response
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersResponse"
  /users/{userid}:
    get:
      operationId: getUser
      summary: Get user by ID
      description: Retrieve details for a specific organizer or sub-organizer.
      tags:
        - Users
      parameters:
        - name: userid
          in: path
          required: true
          description: Unique identifier of the user
          schema:
            type: integer
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersResponse"
  /transactions/{checkout_id}:
    get:
      operationId: getTransactionByCheckoutId
      summary: Get transaction by checkout ID
      description: Retrieve a transaction using its checkout identifier.
      tags:
        - Transactions
      parameters:
        - name: checkout_id
          in: path
          required: true
          description: Checkout identifier for the transaction
          schema:
            type: integer
      responses:
        "200":
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionDetailResponse"
  /transactions/{refno}:
    get:
      operationId: getTransactionByRef
      summary: Get transaction by reference number
      description: Retrieve a transaction using its reference number.
      tags:
        - Transactions
      parameters:
        - name: refno
          in: path
          required: true
          description: Reference number for the transaction
          schema:
            type: string
      responses:
        "200":
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionDetailResponse"
  /attendees/{attendeeid}:
    get:
      operationId: getAttendee
      summary: Get attendee by ID
      description: Retrieve details for a specific attendee.
      tags:
        - Attendees
      parameters:
        - name: attendeeid
          in: path
          required: true
          description: Unique identifier of the attendee
          schema:
            type: integer
      responses:
        "200":
          description: Attendee details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendeeDetailResponse"
  /attendees/checkin:
    post:
      operationId: checkinAttendee
      summary: Check in or revert attendee
      description: Perform a check-in for an attendee or revert a previous check-in.
      tags:
        - Attendees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckinRequest"
      responses:
        "200":
          description: Check-in result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckinResponse"
  /checkout/prepare/{eventid}/{dateid}:
    get:
      operationId: prepareCheckout
      summary: Prepare checkout session
      description: Retrieve payment options, ticket types, and questions to prepare a checkout session.
      tags:
        - Checkout
      parameters:
        - name: eventid
          in: path
          required: true
          description: Unique identifier of the event
          schema:
            type: integer
        - name: dateid
          in: path
          required: true
          description: Unique identifier of the event date
          schema:
            type: integer
      responses:
        "200":
          description: Checkout preparation data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutPrepareResponse"
  /checkout/create:
    post:
      operationId: createCheckout
      summary: Create checkout
      description: Create a checkout session with selected ticket types.
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutCreateRequest"
      responses:
        "200":
          description: Checkout created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutCreateResponse"
  /checkout/fillorder:
    post:
      operationId: fillOrder
      summary: Fill order details
      description: Provide buyer and attendee details for a checkout session.
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutFillOrderRequest"
      responses:
        "200":
          description: Order filled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutFillOrderResponse"
  /checkout/confirm:
    post:
      operationId: confirmCheckout
      summary: Confirm checkout
      description: Confirm a checkout order with payment status.
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutConfirmRequest"
      responses:
        "200":
          description: Checkout confirmed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutConfirmResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Pagination:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
    Category:
      type: object
      properties:
        category:
          type: string
          example: Business
    CategoriesResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: "#/components/schemas/Category"
    Event:
      type: object
      properties:
        id:
          type: number
        title:
          type: string
        description:
          type: string
        currency:
          type: string
        start_date:
          type: string
          format: date-time
        start_time:
          type: string
        end_date:
          type: string
          format: date-time
        end_time:
          type: string
        time_zone:
          type: string
        tickets_sold:
          type: number
        tickets_total:
          type: number
        status:
          type: string
          enum: [live, draft, unpublished, completed]
        show_remaining:
          type: boolean
        twitter_hashtag:
          type: string
        utc_offset:
          type: string
        invite_code:
          type: string
        url:
          type: string
          format: uri
        logo_url:
          type: string
          format: uri
        bgimage_url:
          type: string
          format: uri
        venue:
          type: string
        dateid:
          type: number
        categories:
          type: string
        language:
          type: string
        description_html:
          type: string
        timezone_code:
          type: string
    EventsResponse:
      type: object
      properties:
        pagination:
          type: array
          items:
            $ref: "#/components/schemas/Pagination"
        events:
          type: array
          items:
            $ref: "#/components/schemas/Event"
    Ticket:
      type: object
      properties:
        id:
          type: number
        title:
          type: string
        quantity_total:
          type: string
        price:
          type: string
        description:
          type: string
        sales_start_date:
          type: string
        sales_start_time:
          type: string
          format: date-time
        sales_end_date:
          type: string
          format: date-time
        sales_end_time:
          type: string
        group_discount:
          type: string
        group_percentage:
          type: string
        group_price:
          type: string
        additional_instructions:
          type: string
        unlock_code:
          type: string
        ticket_type:
          type: string
        boxoffice_only:
          type: boolean
        is_visible:
          type: boolean
        limit_minimum:
          type: string
        limit_maximum:
          type: string
        allow_partial_payment:
          type: boolean
        partial_payment_installments:
          type: string
        partial_payment_frequency:
          type: string
        partial_payment_amount:
          type: string
    Donation:
      type: object
      properties:
        donationid:
          type: number
        title:
          type: string
        description:
          type: string
        quantity_total:
          type: number
        donation_minimum:
          type: string
        donation_start_date:
          type: string
          format: date-time
        donation_end_date:
          type: string
          format: date-time
    TicketsResponse:
      type: object
      properties:
        tickets:
          type: array
          items:
            $ref: "#/components/schemas/Ticket"
        donation:
          type: array
          items:
            $ref: "#/components/schemas/Donation"
    Transaction:
      type: object
      properties:
        transaction_ref:
          type: string
        checkout_id:
          type: number
        transaction_date:
          type: string
        transaction_amount:
          type: string
        tickets_in_transaction:
          type: number
        event_date:
          type: string
          format: date-time
        transaction_status:
          type: string
        user_id:
          type: number
        event_id:
          type: number
        title:
          type: string
        email:
          type: string
          format: email
        buyer_first_name:
          type: string
        buyer_last_name:
          type: string
        promo_code:
          type: string
        payment_type:
          type: string
        comments:
          type: string
    TransactionsListResponse:
      type: object
      properties:
        pagination:
          type: array
          items:
            $ref: "#/components/schemas/Pagination"
        transactions:
          type: array
          items:
            $ref: "#/components/schemas/Transaction"
    TransactionDetail:
      type: object
      properties:
        refno:
          type: string
        checkout_id:
          type: number
        transaction_date:
          type: string
        transaction_amount:
          type: number
        tickets_in_transaction:
          type: number
        event_date:
          type: string
          format: date-time
        transaction_status:
          type: string
        user_id:
          type: number
        event_id:
          type: number
        title:
          type: string
        email:
          type: string
          format: email
        buyer_first_name:
          type: string
        buyer_last_name:
          type: string
        promo_code:
          type: string
        payment_type:
          type: string
        comments:
          type: string
        transaction_tax:
          type: number
        transaction_discount:
          type: number
        eventzilla_fee:
          type: number
    TransactionDetailResponse:
      type: object
      properties:
        transaction:
          type: array
          items:
            $ref: "#/components/schemas/TransactionDetail"
    AttendeeListItem:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        ticket_type:
          type: string
        bar_code:
          type: string
        is_attended:
          type: string
        questions:
          type: array
          items:
            type: object
            properties:
              questions:
                type: string
              answer:
                type: string
        transaction_ref:
          type: string
        id:
          type: number
        transaction_date:
          type: string
        transaction_amount:
          type: number
        event_date:
          type: string
        transaction_status:
          type: string
        user_id:
          type: number
        event_id:
          type: number
        title:
          type: string
        email:
          type: string
          format: email
        buyer_first_name:
          type: string
        buyer_last_name:
          type: string
        payment_type:
          type: string
    AttendeesListResponse:
      type: object
      properties:
        attendees:
          type: array
          items:
            $ref: "#/components/schemas/AttendeeListItem"
    AttendeeDetail:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        ticket_type:
          type: string
        bar_code:
          type: string
        is_attended:
          type: string
        questions:
          type: array
          items:
            type: object
            properties:
              questions:
                type: string
              answer:
                type: string
        refno:
          type: string
        id:
          type: string
        transaction_date:
          type: string
        transaction_amount:
          type: string
        transaction_status:
          type: string
        title:
          type: string
        email:
          type: string
          format: email
        buyer_first_name:
          type: string
        buyer_last_name:
          type: string
        payment_type:
          type: string
        event_id:
          type: number
        event_date:
          type: string
          format: date-time
    AttendeeDetailResponse:
      type: object
      properties:
        attendees:
          type: array
          items:
            $ref: "#/components/schemas/AttendeeDetail"
    CheckinRequest:
      type: object
      required:
        - barcode
        - eventcheckin
      properties:
        barcode:
          type: string
          description: Attendee barcode
        eventcheckin:
          type: boolean
          description: true to check in, false to revert check-in
    CheckinResponse:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        eventtitle:
          type: string
        orderef:
          type: string
        email:
          type: string
          format: email
        status:
          type: string
          enum: [Checkin, Checkout]
    ToggleSalesRequest:
      type: object
      required:
        - eventid
        - status
      properties:
        eventid:
          type: integer
        status:
          type: boolean
          description: true to publish, false to unpublish
    ToggleSalesResponse:
      type: object
      properties:
        eventstatus:
          type: string
          enum: [published, unpublished]
    OrderConfirmRequest:
      type: object
      required:
        - checkout_id
        - eventid
      properties:
        checkout_id:
          type: integer
        eventid:
          type: integer
        comments:
          type: string
        sendemail:
          type: boolean
          default: true
    OrderConfirmResponse:
      type: object
      properties:
        orderconfirm:
          type: string
          example: success
    OrderCancelRequest:
      type: object
      required:
        - checkout_id
        - eventid
      properties:
        checkout_id:
          type: integer
        eventid:
          type: integer
        comments:
          type: string
    OrderCancelResponse:
      type: object
      properties:
        ordercancel:
          type: string
          example: success
    User:
      type: object
      properties:
        id:
          type: number
        username:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        company:
          type: string
        address_line1:
          type: string
        address_line2:
          type: string
        zip_code:
          type: string
        address_locality:
          type: string
        address_region:
          type: string
        address_country:
          type: string
        email:
          type: string
          format: email
        timezone:
          type: string
        website:
          type: string
          format: uri
        phone_primary:
          type: string
        avatar_url:
          type: string
          format: uri
        facebook_id:
          type: string
        twitter_id:
          type: string
        last_seen:
          type: string
        user_type:
          type: string
          enum: [organizer, sub-organizer]
    UsersResponse:
      type: object
      properties:
        pagination:
          type: array
          items:
            $ref: "#/components/schemas/Pagination"
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
    PaymentOption:
      type: object
      properties:
        payment_id:
          type: number
        paymentoption_name:
          type: string
    TicketTypeOption:
      type: object
      properties:
        ticket_type_id:
          type: number
        ticket_type_name:
          type: string
        ticket_type_price:
          type: string
        ticket_type_min_limit:
          type: number
        ticket_type_max_limit:
          type: number
        ticket_type_avail_quantity:
          type: number
        ticket_type_onsale:
          type: boolean
        ticket_type_description:
          type: string
    Question:
      type: object
      properties:
        question_id:
          type: number
        question_type:
          type: string
        question_text:
          type: string
        question_choices:
          type: array
          items:
            type: string
        question_waiver:
          type: string
        has_subquestion:
          type: boolean
        subquestion_rules:
          type: array
          items: {}
    Tax:
      type: object
      properties:
        tax_type:
          type: string
        tax_name:
          type: string
        tax_value:
          type: string
    CheckoutPrepareResponse:
      type: object
      properties:
        payment_options:
          type: array
          items:
            $ref: "#/components/schemas/PaymentOption"
        tickettypes:
          type: array
          items:
            $ref: "#/components/schemas/TicketTypeOption"
        questions:
          type: array
          items:
            $ref: "#/components/schemas/Question"
        discount_enabled:
          type: boolean
        tax_enabled:
          type: boolean
        tax:
          type: array
          items:
            $ref: "#/components/schemas/Tax"
    TicketSelection:
      type: object
      properties:
        ticket_type_id:
          type: number
        quantity:
          type: number
    CheckoutCreateRequest:
      type: object
      required:
        - eventid
        - eventdateid
        - ticket_types
      properties:
        eventid:
          type: integer
        eventdateid:
          type: integer
        ticket_types:
          type: array
          items:
            $ref: "#/components/schemas/TicketSelection"
        discount_code:
          type: string
    CheckoutTicket:
      type: object
      properties:
        ticket_price_id:
          type: number
        ticket_type_id:
          type: number
        ticket_type_name:
          type: string
    CheckoutCreateResponse:
      type: object
      properties:
        checkout_id:
          type: number
        transaction_ref:
          type: string
        transaction_total:
          type: number
        transaction_tax:
          type: number
        transaction_discount:
          type: number
        eventzilla_fee:
          type: number
        currency:
          type: string
        tickets:
          type: array
          items:
            $ref: "#/components/schemas/CheckoutTicket"
    BuyerDetails:
      type: object
      properties:
        buyer_firstname:
          type: string
        buyer_lastname:
          type: string
        buyer_email:
          type: string
          format: email
    AnswerItem:
      type: object
      properties:
        question_id:
          type: number
        answer_text:
          type: string
    TicketFillItem:
      type: object
      properties:
        ticket_price_id:
          type: number
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        answers:
          type: array
          items:
            $ref: "#/components/schemas/AnswerItem"
    CheckoutFillOrderRequest:
      type: object
      required:
        - eventid
        - eventdateid
        - checkout_id
        - buyerdetails
        - tickets
        - payment_id
      properties:
        eventid:
          type: integer
        eventdateid:
          type: integer
        checkout_id:
          type: integer
        buyerdetails:
          type: array
          items:
            $ref: "#/components/schemas/BuyerDetails"
        tickets:
          type: array
          items:
            $ref: "#/components/schemas/TicketFillItem"
        payment_id:
          type: integer
    CheckoutFillOrderResponse:
      type: object
      properties:
        checkout_id:
          type: number
        transaction_ref:
          type: string
        transaction_total:
          type: number
        transaction_tax:
          type: number
        transaction_discount:
          type: number
        transaction_status:
          type: string
        eventzilla_fee:
          type: number
        currency:
          type: string
    CheckoutConfirmRequest:
      type: object
      required:
        - eventid
        - eventdateid
        - checkout_id
        - payment_status
      properties:
        eventid:
          type: integer
        eventdateid:
          type: integer
        checkout_id:
          type: integer
        payment_status:
          type: string
        comments:
          type: string
        sendemail:
          type: boolean
          default: true
    CheckoutConfirmResponse:
      type: object
      properties:
        checkout_id:
          type: number
        transaction_ref:
          type: string
        transaction_total:
          type: number
        transaction_tax:
          type: number
        transaction_discount:
          type: number
        eventzilla_fee:
          type: number
        transaction_status:
          type: string
        confirmation_email_sent:
          type: boolean
        currency:
          type: string