openapi: 3.1.0
info:
  title: Howler API v3 Artists Top Up API
  version: 3.6.1
  description: '*Last updated: 2026-01-20 21:15:49 +0200*

    '
servers:
- url: https://{defaultHost}/api/v3/consumer_portal
  variables:
    defaultHost:
      default: www.howler.co.za
  description: Server for consumer portal endpoints
security:
- bearer_header: []
  bearer_param: []
  api_key: []
  bearer_auth: []
tags:
- name: Top Up
paths:
  /top_up:
    post:
      summary: select ticket or cashless tag (1)
      operationId: updateConsumerTopup
      tags:
      - Top Up
      parameters: []
      description: 'Start the top up process of either a ticket or cashless tag by proving the barcode of the ticket or the uid of the cashless tag.


        The next_step in the body will indicate which action should be performed next.


        Whether the provided barcode or uid is a ticket or cashless tag will also depend on the response. Either the ticket or cashless_tag property will be populated.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                Ticket:
                  value:
                    top_up_order:
                      id: 1
                      reference: '123'
                      status: pending
                      type: TopUpOrder
                      user: {}
                    ticket:
                      id: 2
                      barcode: '1234'
                    next_step: /api/v3/consumer_portal/tickets/2/top_up/1/amounts
                Cashless Tag:
                  value:
                    top_up_order:
                      id: 4
                      reference: '123'
                      status: pending
                      type: TopUpOrder
                      user: {}
                    cashless_tag:
                      id: 3
                      uid: 1234EEEEE
                    next_step: /api/v3/consumer_portal/cashless_tags/1234EEEEE/top_up/4/amounts
              schema:
                type: object
                properties:
                  top_up_order:
                    $ref: '#/components/schemas/Order'
                  ticket:
                    $ref: '#/components/schemas/Ticket'
                  cashless_tag:
                    $ref: '#/components/schemas/CashlessTag'
                  next_step:
                    type: string
                required:
                - top_up_order
                - next_step
        '404':
          description: topupable not found
        '400':
          description: topups not available
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                barcode_or_uid:
                  type: string
              required:
              - barcode_or_uid
            examples:
              ticket:
                summary: Ticket
                value:
                  barcode_or_uid: '1234'
              cashless_tag:
                summary: Cashless Tag
                value:
                  barcode_or_uid: 1234EEEEE
        required: true
components:
  schemas:
    Answer:
      type: object
      properties:
        id:
          type: integer
          description: Answer ID
        question_id:
          type: integer
          description: ID of the question this answer belongs to
        response:
          type:
          - string
          - 'null'
          - array
          description: The answer text
      required:
      - id
      - question_id
      - response
    UserValidationConfiguration:
      type: object
      properties:
        require_id_number?:
          type: boolean
          description: South African ID number is required
        require_unique_identifier?:
          type: boolean
          description: ''
        require_first_name?:
          type: boolean
          description: First Name is required
        require_last_name?:
          type: boolean
          description: Last Name is required
        require_cellphone_number?:
          type: boolean
          description: Cellphone Number is required
        require_country?:
          type: boolean
          description: Country of Residence is required
        require_passport_country?:
          type: boolean
          description: Passport Country is required
        require_city?:
          type: boolean
          description: City of Residence is required
        require_gender?:
          type: boolean
          description: Gender is required
        require_date_of_birth?:
          type: boolean
          description: Date of Birth is required
        require_passport_number?:
          type: boolean
          description: Passport Number is required
        require_nickname?:
          type: boolean
          description: Nickname is required
        require_billing_address?:
          type: boolean
          description: Nilling Address is required
      required:
      - require_id_number?
      - require_unique_identifier?
      - require_first_name?
      - require_last_name?
      - require_cellphone_number?
      - require_country?
      - require_passport_country?
      - require_city?
      - require_gender?
      - require_date_of_birth?
      - require_passport_number?
      - require_nickname?
      - require_billing_address?
      description: Indicates which user details need to be completed before their profile is considered setup for an event.
    CashlessTag:
      type: object
      properties:
        id:
          type: integer
        event_id:
          type: integer
        uid:
          type: string
        tag_type:
          type: string
          enum:
          - card
          - wristband
      required:
      - id
      - uid
    Addonable:
      type:
      - object
      - 'null'
      properties:
        name:
          type: string
          description: Name
        size:
          type: string
          description: Size
      required:
      - name
      - size
    Order:
      type: object
      properties:
        id:
          type: integer
        reference:
          type: string
        type:
          type: string
        status:
          type: string
          enum:
          - pending
          - paid
          - expired
          - pending_payment
          - created
          - processing
        user:
          $ref: '#/components/schemas/User'
        cashless_deposit_cents:
          type: integer
      required:
      - id
      - reference
      - status
      - type
      - user
      - cashless_deposit_cents
    TicketType:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
        name:
          type: string
        ticket_category:
          $ref: '#/components/schemas/TicketCategory'
          nullable: true
        cost:
          type: integer
        fee:
          type: integer
        booking_status:
          type: string
        virtual_credit_cents:
          type:
          - integer
          - 'null'
        description:
          type: string
        image_url:
          type:
          - string
          - 'null'
          description: URL to the ticket type image if attached
        topups_configuration:
          $ref: '#/components/schemas/TopupsConfiguration'
        customer_settings_configuration:
          $ref: '#/components/schemas/CustomerSettingsConfiguration'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
          description: Questions associated with this ticket type
        hidden:
          type: boolean
        hidden_by_promo_code:
          type: boolean
      required:
      - id
      - updated_at
      - created_at
      - topups_configuration
    Question:
      type: object
      properties:
        id:
          type: integer
          description: Question ID
        text:
          type: string
          description: Question text
        required:
          type: boolean
          description: Whether the question is required
        question_type:
          type: string
          description: Type of question
          enum:
          - text
          - number
          - multiple_choice
          - multiple_answer
          - date
          - boolean
          - cellphone_number
          - id_number
        options:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Available options for multiple choice questions
        position:
          type: integer
          description: Display position of the question
      required:
      - id
      - text
      - required
      - question_type
    TopupsConfiguration:
      type: object
      properties:
        topups_enabled?:
          type: boolean
          description: Top Ups are enabled for the event
        prevent_topup_for_multiple_tickets_of_same_type?:
          type: boolean
          description: If a user own mutliple tickets of the same ticket type then they cannot bt topped up.
        small_topup_amount:
          type: integer
          description: Small Topup Amount
        medium_topup_amount:
          type: integer
          description: Medium Topup Amount
        large_topup_amount:
          type: integer
          description: Large Topup Amount
      required:
      - topups_enabled?
      - small_topup_amount
      - medium_topup_amount
      - large_topup_amount
    Venue:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Primary Key
        address:
          type: string
          description: Address
        external_identifier:
          type:
          - string
          - 'null'
          description: External Identifier
        latitude:
          type: string
          description: Latitude
        longitude:
          type: string
          description: Longitude
        name:
          type: string
          description: Name
        source:
          type:
          - string
          - 'null'
          description: Source
      required:
      - id
      - address
      - external_identifier
      - latitude
      - longitude
      - name
      - source
    Ticket:
      type: object
      properties:
        id:
          type: integer
        barcode:
          type:
          - string
          - 'null'
        personalised_name:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - pending
          - pending_payment
          - active
          - expired
          - closed
          - transferred
          - refunded
          - reseated
          - pending_assignment
          - on_resale
          - sold
          - pending_allocation
        created_at:
          type: string
          format: ISO 8601
        event_id:
          type: integer
        event:
          $ref: '#/components/schemas/Event'
          nullable: true
        ticket_type:
          $ref: '#/components/schemas/TicketType'
        is_addonable?:
          type: boolean
        addonable:
          $ref: '#/components/schemas/Addonable'
        updated_at:
          type: string
          format: ISO 8601
        scanned_at:
          type:
          - string
          - 'null'
          format: ISO 8601
        user:
          anyOf:
          - $ref: '#/components/schemas/User'
          - type: 'null'
        purchaser:
          $ref: '#/components/schemas/User'
        cashless_tag_uid:
          type:
          - string
          - 'null'
        can_be_transferred?:
          type: boolean
        can_be_topped_up?:
          type: boolean
        can_be_downloaded?:
          type: boolean
        can_show_barcode?:
          type: boolean
        active_status:
          type: string
          enum:
          - pending
          - pending_payment
          - active
          - expired
          - closed
          - transferred
          - refunded
          - reseated
          - pending_assignment
          - on_resale
          - sold
          - pending_allocation
          - incomplete_registration
          - refund_processing
          - transfer_pending
          - resale_pending_purchase
          - assignment_pending
        claimed?:
          type: boolean
        can_edit_ticket_transfer?:
          type: boolean
        registered?:
          type: boolean
        total_top_up_amount_cents:
          type: integer
        download_url:
          type:
          - string
          - 'null'
        answers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Answer'
          description: Answers to ticket questions
      required:
      - id
      - personalised_name
      - barcode
      - status
      - purchaser
      - updated_at
      - created_at
      - event_id
      - event
      - ticket_type
      - is_addonable?
      - addonable
      - can_be_transferred?
      - can_be_topped_up?
      - can_show_barcode?
      - claimed?
    TicketCategory:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        position:
          type: integer
        description:
          type: string
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
      required:
      - id
      - name
      - position
      - created_at
      - updated_at
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Primary Key
        first_name:
          type: string
          description: First Name
        last_name:
          type: string
          description: Last Name
        primary_email:
          type: string
          readOnly: true
          description: Email address of user or dummy user
        dummy?:
          type: boolean
          readOnly: true
          description: True if the user has not yet signed up for an account.
      required:
      - id
      - first_name
      - last_name
      - primary_email
      - dummy?
    CustomerSettingsConfiguration:
      type: object
      properties:
        customer_transfers_enabled?:
          type: boolean
          description: Ticket transfers are allowed
        require_signup_for_ticket_downloads?:
          type: boolean
          description: User profile must be setup, all required data capture completed and marketing questions answered before a user can download their tickets.
        ticket_downloads_enabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
          description: Specified date and time when tickets will be able to be downloaded.
        ticket_downloads_enabled?:
          type: boolean
          description: If true a user will be able to download their tickets at the specified date and time
        show_ticket_barcode?:
          type: boolean
          description: If tickets cannot be downloaded and this is true then the user will be able to see their barcode number of their ticket as text but not download or view it.
        sharing_required_enabled?:
          type: boolean
          description: Sharing required enabled.
      required: []
    Event:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Name of the event
        ticket_types:
          type: array
          items:
            $ref: '#/components/schemas/TicketType'
          description: List of ticket types available for this event
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/TicketType'
          description: List of addon ticket types for the event
        status:
          type: string
          enum:
          - pending
          - active
          - cancelled
        start_time:
          type:
          - string
          - 'null'
          format: ISO 8601
        end_time:
          type:
          - string
          - 'null'
          format: ISO 8601
        currency:
          type: string
          description: ISO 4217 Currency Code
        cashouts_enabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
        cashouts_disabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
        auto_cashouts_enabled?:
          type: boolean
          description: Event supports auto cashouts
        claim_barcode_feature?:
          type: boolean
          description: Tickets can be claimed by topping them up.
        enable_live_topups?:
          type: boolean
          description: Topups are allowed during the event.
        slug:
          type: string
          description: 'URL slug used for the event. The url for the event can be generated as follows: https://{baseUrl}/events/{slug}'
        short_url:
          type:
          - string
          - 'null'
          description: 'Short URL slug used for the event. The url for the event can be generated as follows: https://{baseUrl}/{short_url}'
        classification:
          type: string
          enum:
          - howler
          - howler_ticketing
          - howler_cashless
          - foreign_ticketing
        venue:
          $ref: '#/components/schemas/Venue'
        artist_lineup:
          type: array
          items:
            $ref: '#/components/schemas/ArtistLineup'
          description: List of artists performing at the event
        my_artist_lineup:
          type: array
          items:
            $ref: '#/components/schemas/ArtistLineup'
          description: List of this user's performances for the event
        is_cashless?:
          type: boolean
        is_past_event?:
          type: boolean
        user_validation_configuration:
          $ref: '#/components/schemas/UserValidationConfiguration'
        onsite_top_up_available?:
          type: boolean
        cashless_deposit_cents:
          type: integer
        header_image_url:
          type:
          - string
          - 'null'
        live:
          type: boolean
        mapboxUrl:
          type:
          - string
          - 'null'
      required:
      - id
      - name
      - currency
      - auto_cashouts_enabled?
      - slug
      - enable_live_topups?
      - onsite_top_up_available?
      - header_image_url
      - is_past_event?
      - live
      - ticket_types
      - add_ons
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication for third-party applications
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            public: Public scope
            login: Login scope
            ott: One-time token scope
    bearer_header:
      type: http
      scheme: bearer
      bearerFormat: oauth2
      in: header
    bearer_param:
      type: apiKey
      scheme: bearer
      bearerFormat: oauth2
      name: bearer_token
      in: query
    jwt_header:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from basic authentication login
    jwt_param:
      type: apiKey
      name: bearer_token
      in: query
      description: JWT token as query parameter (alternative to Authorization header)
    basic_auth:
      type: http
      scheme: basic
      description: Basic authentication with email and password
    api_key:
      type: apiKey
      name: x-auth-token
      in: header
      description: API key authentication
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication