openapi: 3.0.0
info:
  title: Ticketing
  version: "1.0"
  description: The Ticketing service is responsible for post purchase ticket
    management, including viewing your tickets (and contacts you are associated
    to, such as a father seeing a son's season ticket), as well as features such
    as forwarding and recalling.
tags:
  - name: Ticketing
paths:
  /tickets:
    get:
      operationId: get-tickets
      summary: Get Tickets
      description: Get the tickets for the current authenticated contact (those that
        they bought themselves, or those that were forwarded to them). This
        endpoint also returns tickets for other contacts that this current
        contact has been explicitly associated to with the
        `ticketing.tickets.read` scope.
      parameters:
        - name: eventId
          in: query
          required: false
          description: event identifier to filter tickets
          schema:
            type: string
          explode: false
        - name: currentSeason
          in: query
          required: false
          description: when true, return only tickets for the current season — those whose
            event has not finished before the configured season start, including
            fixtures already played; omitted or false returns tickets for all
            dates
          schema:
            type: boolean
          explode: false
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TicketDto"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
  /tickets/events:
    get:
      operationId: get-events
      summary: Get Events
      description: Get the events with aggregated tickets number for the current
        authenticated contact (those that they bought themselves, or those that
        were forwarded to them).
      parameters: []
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AggregatedTicketsEventDto"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
  /tickets/paged:
    get:
      operationId: get-tickets-paged
      summary: Get Tickets (paged)
      description: Get a single page of tickets for the current authenticated contact,
        wrapped in a paging envelope. Accepts the same filters as GET /tickets
        plus the required `page` and `pageSize` parameters.
      parameters:
        - name: eventId
          in: query
          required: false
          description: event identifier to filter tickets
          schema:
            type: string
          explode: false
        - name: forwardingStatus
          in: query
          required: false
          description: filter tickets by forwarding status; repeat the parameter to match
            multiple statuses
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ForwardingStatusEnum"
          style: form
          explode: true
        - name: from
          in: query
          required: false
          description: inclusive lower bound (UTC, ISO-8601) on the event's effective time
            (end, or start when no end); omit for no lower bound
          schema:
            type: string
            format: date-time
          explode: false
        - name: to
          in: query
          required: false
          description: inclusive upper bound (UTC, ISO-8601) on the event's effective time
            (end, or start when no end); omit for no upper bound
          schema:
            type: string
            format: date-time
          explode: false
        - name: page
          in: query
          required: true
          description: 1-based page number to return
          schema:
            type: integer
            format: int32
          explode: false
        - name: pageSize
          in: query
          required: true
          description: maximum number of tickets per page
          schema:
            type: integer
            format: int32
          explode: false
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedTicketsDto"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
  /tickets/{ticketId}/accept:
    post:
      operationId: accept-ticket
      summary: accept forwarded ticket
      description: Attempt to accept received ticket.
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The id of the ticket to be accepted.
          schema:
            type: string
      responses:
        "202":
          description: The request has been accepted for processing, but processing has
            not yet completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForwardTicketsResponse"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
  /tickets/{ticketId}/forward:
    post:
      operationId: forward-tickets
      summary: Forward a ticket
      description: Attempt to forward a ticket to another contact. Depending on the
        ticketing provider in question, the rules around who a ticket can be
        forwarded to may vary.
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The id of the ticket to be forwarded.
          schema:
            type: string
      responses:
        "202":
          description: The request has been accepted for processing, but processing has
            not yet completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForwardTicketsResponse"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForwardTicketBody"
  /tickets/{ticketId}/pass:
    post:
      operationId: pass
      summary: Create pass
      description: Generates wallet pass for given ticket
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The id of the ticket.
          schema:
            type: string
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a
            result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateWalletResponseDto"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
        "404":
          description: The server cannot find the requested resource.
        "500":
          description: Server error
      tags:
        - Ticketing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWalletPass"
  /tickets/{ticketId}/recall:
    post:
      operationId: recall-ticket
      summary: Recall a ticket
      description: Recall a ticket that has been forwarded to another contact
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The id of the ticket to be recalled.
          schema:
            type: string
      responses:
        "202":
          description: The request has been accepted for processing, but processing has
            not yet completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecallTicketsResponse"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
        "404":
          description: The server cannot find the requested resource.
      tags:
        - Ticketing
  /tickets/{ticketId}/reject:
    post:
      operationId: reject-ticket
      summary: reject forwarded ticket
      description: Attempt to reject received ticket.
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The id of the ticket to be rejected.
          schema:
            type: string
      responses:
        "202":
          description: The request has been accepted for processing, but processing has
            not yet completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForwardTicketsResponse"
        "400":
          description: The server could not understand the request due to invalid syntax.
        "401":
          description: Access is unauthorized.
      tags:
        - Ticketing
security:
  - BearerAuth: []
    ApiKeyAuth: []
components:
  schemas:
    AggregatedTicketsEventDto:
      type: object
      required:
        - ticketsNumber
        - additionalFields
      properties:
        ticketsNumber:
          type: integer
          format: int32
        additionalFields:
          type: object
          additionalProperties: {}
      allOf:
        - $ref: "#/components/schemas/EventDto"
    CapabilityEnum:
      type: string
      enum:
        - CAN_FORWARD
        - CAN_RECALL
    ContactDto:
      type: object
      properties:
        contactId:
          type: string
        name:
          type: string
    ContactsDto:
      type: object
      required:
        - purchaser
        - isOwner
      properties:
        purchaser:
          allOf:
            - $ref: "#/components/schemas/ContactDto"
          description: The contact that purchased the ticket
        assignee:
          allOf:
            - $ref: "#/components/schemas/ContactDto"
          description: The contact that the ticket has been assigned to. This might be the
            purchaser or another contact that the ticket has been forwarded to.
        isOwner:
          type: boolean
    CreateWalletPass:
      type: object
      required:
        - pushNotificationToken
      properties:
        pushNotificationToken:
          type: string
          description: push notification token
    CreateWalletResponseDto:
      type: object
      required:
        - file
        - metadata
      properties:
        file:
          type: string
          description: pkfile base64 encoded
        metadata:
          $ref: "#/components/schemas/WalletMetadataResponseDto"
    EventDto:
      type: object
      required:
        - id
        - name
        - type
        - start
      properties:
        id:
          type: string
        name:
          type: string
        type:
          $ref: "#/components/schemas/EventTypeEnum"
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        image:
          type: string
          format: uri
        venue:
          $ref: "#/components/schemas/VenueDto"
        sportsMatch:
          $ref: "#/components/schemas/SportsMatchDto"
    EventTypeEnum:
      type: string
      enum:
        - NOT_SET
        - SPORTS_MATCH
        - CONCERT
    ForwardTicketBody:
      oneOf:
        - $ref: "#/components/schemas/ForwardTicketFullName"
        - $ref: "#/components/schemas/ForwardTicketContactId"
    ForwardTicketContactId:
      type: object
      required:
        - contactId
      properties:
        contactId:
          type: string
          description: contact id
    ForwardTicketFullName:
      type: object
      required:
        - firstName
        - lastName
        - emailAddress
      properties:
        firstName:
          type: string
          description: The name of the contact being forwarded to.
        lastName:
          type: string
          description: The last name of the contact
        emailAddress:
          type: string
          format: email
          description: The email of the contact being forwarded to.
    ForwardTicketsResponse:
      type: object
      required:
        - notificationId
      properties:
        notificationId:
          type: string
    ForwardingStatusEnum:
      type: string
      enum:
        - NONE
        - IN_PROGRESS
        - PENDING_ACCEPTANCE
        - COMPLETED
    MoneyDto:
      type: object
      required:
        - minorUnits
        - precision
        - currencyCode
      properties:
        minorUnits:
          type: integer
          format: int32
        precision:
          type: integer
          format: int32
        currencyCode:
          type: string
    PagedTicketsDto:
      type: object
      required:
        - results
        - page
        - pageSize
        - pageTotal
        - resultsTotal
        - hasNextPage
        - hasPreviousPage
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/TicketDto"
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        pageTotal:
          type: integer
          format: int32
        resultsTotal:
          type: integer
          format: int32
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
      description: Paged envelope returned by GET /tickets when page & pageSize are
        supplied. Mirrors the shape of Stadion.Framework's PagedResult<T>.
    PriceDto:
      type: object
      required:
        - buyerType
      properties:
        cost:
          $ref: "#/components/schemas/MoneyDto"
        buyerType:
          type: string
    QrCodeDto:
      type: object
      required:
        - code
        - availabilityFrom
      properties:
        code:
          type: string
        availabilityFrom:
          type: string
          format: date-time
          description: The date from which the qr code should be displayed
      description: The code that can be scanned at access control in the Stadium to
        allow access
    RecallTicketsResponse:
      type: object
      required:
        - notificationId
      properties:
        notificationId:
          type: string
    SeatingDto:
      type: object
      required:
        - details
      properties:
        additionalMessage:
          type: string
        details:
          type: object
          additionalProperties:
            type: string
    SportsMatchDto:
      type: object
      required:
        - teams
        - competition
        - competitionKey
      properties:
        teams:
          $ref: "#/components/schemas/TeamsDto"
        competition:
          type: string
        competitionKey:
          type: string
    TeamDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        logo:
          type: string
          format: uri
    TeamTypeEnum:
      type: string
      enum:
        - Unspecified
        - Men
        - Women
    TeamsDto:
      type: object
      required:
        - home
        - away
        - teamType
      properties:
        home:
          $ref: "#/components/schemas/TeamDto"
        away:
          $ref: "#/components/schemas/TeamDto"
        teamType:
          $ref: "#/components/schemas/TeamTypeEnum"
    TicketDto:
      type: object
      required:
        - id
        - providerId
        - contacts
        - event
        - capabilities
        - status
        - forwardingStatus
        - ticketType
        - ticketPackage
        - qrCode
        - price
        - seating
      properties:
        id:
          type: string
        providerId:
          type: string
        contacts:
          $ref: "#/components/schemas/ContactsDto"
        event:
          $ref: "#/components/schemas/EventDto"
        capabilities:
          type: array
          items:
            $ref: "#/components/schemas/CapabilityEnum"
        status:
          $ref: "#/components/schemas/TicketStatusEnum"
        forwardingStatus:
          $ref: "#/components/schemas/ForwardingStatusEnum"
        ticketType:
          $ref: "#/components/schemas/TicketTypeEnum"
        ticketPackage:
          $ref: "#/components/schemas/TicketPackageDto"
        qrCode:
          $ref: "#/components/schemas/QrCodeDto"
        price:
          $ref: "#/components/schemas/PriceDto"
        seating:
          $ref: "#/components/schemas/SeatingDto"
    TicketPackageDto:
      type: object
      required:
        - items
      properties:
        items:
          type: object
          additionalProperties:
            type: string
    TicketStatusEnum:
      type: string
      enum:
        - NOT_SET
        - NOT_SCANNED
        - SCANNED
        - CANCELLED
        - SUSPENDED
    TicketTypeEnum:
      type: string
      enum:
        - VIP
        - GA
        - SC
    VenueDto:
      type: object
      required:
        - name
        - city
        - street
        - postalCode
      properties:
        name:
          type: string
        city:
          type: string
        street:
          type: string
        postalCode:
          type: string
        latitude:
          type: string
        longitude:
          type: string
    WalletMetadataResponseDto:
      type: object
      required:
        - serialNumber
      properties:
        serialNumber:
          type: string
          description: pass serial number
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
servers:
  - url: "{baseUrl}"
    description: Your Storefront API host
    variables:
      baseUrl:
        default: https://your-storefront-api-host
        description: The Storefront API base URL for your store. Your Stadion technical
          contact provides it.