Howler Top Up API
The Top Up API from Howler — 1 operation(s) for top up.
OpenAPI Specification
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