HangHut API
Integrate event ticketing directly into your website or mobile app. List events, sell tickets through hosted checkout, and verify tickets at the door — all with simple REST calls.
Base URL
https://www.hanghut.com/api/v1
Endpoints
Authentication
Authenticate every request with your API key in the Authorization header as a Bearer token.
Keys are generated from your Organizer Dashboard. All keys begin with hh_live_.
Header
Authorization: Bearer hh_live_3dd28059a859bddb...
Example Request
curl https://www.hanghut.com/api/v1/events \ -H "Authorization: Bearer hh_live_your_key"
Rate Limits
Requests are rate limited per API key using a sliding window. Exceeding returns 429.
Response
429{
"error": {
"message": "Rate limit exceeded. Max 100 requests per minute.",
"status": 429
}
}Wait for the window to reset (60 seconds) before retrying.
Errors
All errors return a consistent JSON structure.
| Code | Description |
|---|---|
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — bad or missing API key |
| 404 | Not found |
| 409 | Conflict — sold out or unavailable |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Response
404{
"error": {
"message": "Event not found",
"status": 404
}
}/eventsReturns a paginated list of events for your organization. Includes ticket tiers and real-time sold counts.
Query Parameters
| page | integer | Page numberDefault: 1 |
| per_page | integer | Results per page (max 50)Default: 20 |
| status | string | Filter: active, draft, cancelledDefault: active |
Request
curl "https://www.hanghut.com/api/v1/events?page=1&per_page=10" \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"events": [
{
"id": "bdb74865-8347-...",
"title": "Tinda Tindahan",
"status": "active",
"start_datetime": "2026-04-14T11:07:00+00:00",
"end_datetime": null,
"venue_name": "98 Escolta St",
"city": "Manila",
"capacity": 100,
"cover_image_url": "https://api.hanghut.com/storage/v1/...",
"ticket_price": 700,
"event_type": "art",
"tickets_sold": 10,
"ticket_tiers": [
{
"id": "a8af9742-...",
"name": "General Admission",
"price": 700,
"quantity_total": 100,
"quantity_sold": 0,
"is_active": true,
"sort_order": 0
}
]
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 2,
"total_pages": 1,
"has_more": false
}
}
}/events/:idReturns full event details including description, venue, images, and ticket tiers with real-time available counts per tier.
Path Parameters
| id | uuid | Event IDREQUIRED |
Each tier includes an available field (quantity_total - quantity_sold).
Request
curl "https://www.hanghut.com/api/v1/events/8db0f243-2e64-..." \ -H "Authorization: Bearer hh_live_your_key"
/eventsCreate a new event. Events are created in draft status by default.
Request Body
| title | string | Event nameREQUIRED |
| start_datetime | ISO 8601 | Start date/timeREQUIRED |
| end_datetime | ISO 8601 | End date/time |
| venue_name | string | Venue name |
| city | string | City |
| capacity | integer | Max attendees |
| ticket_price | number | Base price in PHP |
Request
curl -X POST "https://www.hanghut.com/api/v1/events" \
-H "Authorization: Bearer hh_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Friday Night Comedy",
"start_datetime": "2026-04-10T20:00:00+08:00",
"venue_name": "Comedy Bar Manila",
"city": "Manila",
"capacity": 150,
"ticket_price": 800
}'Response
201{
"data": {
"id": "f47ac10b-58cc-...",
"title": "Friday Night Comedy",
"status": "draft",
"start_datetime": "2026-04-10T20:00:00+08:00",
"venue_name": "Comedy Bar Manila",
"capacity": 150,
"ticket_price": 800
}
}/events/:idUpdate event details. Only include fields you want to change. Set status to active to publish.
Request
curl -X PUT "https://www.hanghut.com/api/v1/events/f47ac10b-..." \
-H "Authorization: Bearer hh_live_your_key" \
-H "Content-Type: application/json" \
-d '{"status": "active", "capacity": 200}'/events/:id/attendeesPaginated list of attendees. Filter by ticket status for guest lists or export.
Query Parameters
| page | integer | Page numberDefault: 1 |
| per_page | integer | Results per page (max 100) |
| status | string | Filter: sold, checked_in, refunded |
Request
curl "https://www.hanghut.com/api/v1/events/8db0f243-.../attendees?status=sold" \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"event": { "id": "8db0f243-...", "title": "S10MAIC" },
"attendees": [
{
"ticket_id": "a1b2c3d4-...",
"ticket_number": "TK-00042",
"status": "sold",
"checked_in_at": null,
"customer": {
"name": "Juan Dela Cruz",
"email": "juan@example.com"
},
"tier": { "name": "General Admission", "price": 1000 }
}
],
"meta": { "page": 1, "total": 85, "has_more": true }
}
}/checkoutsCreates a hosted checkout session. Redirect your customer to the returned URL to complete payment via GCash, Maya, bank transfer, or card.
Request Body
| event_id | uuid | Event to buy tickets forREQUIRED |
| tier_id | uuid | Ticket tier (default if omitted) |
| quantity | integer | Number of tickets (min 1)REQUIRED |
| customer.name | string | Customer full nameREQUIRED |
| customer.email | string | Email for ticket deliveryREQUIRED |
| customer.phone | string | Phone number |
| success_url | string | Redirect after paymentREQUIRED |
| cancel_url | string | Redirect if cancelled |
Request
curl -X POST "https://www.hanghut.com/api/v1/checkouts" \
-H "Authorization: Bearer hh_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"event_id": "8db0f243-2e64-...",
"tier_id": "66a5cdd3-d097-...",
"quantity": 2,
"customer": {
"name": "Juan Dela Cruz",
"email": "juan@example.com"
},
"success_url": "https://your-site.com/success",
"cancel_url": "https://your-site.com/cancel"
}'Response
201{
"data": {
"checkout_id": "pi_abc123def456",
"checkout_url": "https://checkout.hanghut.com/...",
"expires_at": "2026-03-22T00:00:00Z"
}
}/tickets/:idVerify a ticket's status, check-in state, and associated event/customer details.
Path Parameters
| id | uuid | Ticket IDREQUIRED |
Ticket Statuses
sold | Valid, ready for check-in |
checked_in | Already scanned |
refunded | Refunded |
cancelled | Cancelled |
Request
curl "https://www.hanghut.com/api/v1/tickets/a1b2c3d4-..." \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"id": "a1b2c3d4-...",
"status": "sold",
"checked_in_at": null,
"purchased_at": "2026-03-21T10:30:00Z",
"event": {
"id": "8db0f243-...",
"title": "S10MAIC",
"start_datetime": "2026-03-27T19:00:00+00:00",
"venue_name": "Mow's"
},
"tier": {
"name": "General Admission",
"price": 1000
},
"customer": {
"name": "Juan Dela Cruz",
"email": "juan@example.com"
}
}
}/tickets/:id/check-inMark a ticket as checked in. Returns 409 if already used, refunded, or cancelled.
Request
curl -X POST "https://www.hanghut.com/api/v1/tickets/a1b2c3d4-.../check-in" \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"id": "a1b2c3d4-...",
"status": "used",
"checked_in_at": "2026-03-27T19:15:00Z",
"event": { "id": "8db0f243-...", "title": "S10MAIC" },
"customer": { "name": "Juan Dela Cruz" }
}
}/tickets/:id/refundMark a ticket as refunded. Updates status and decrements sold count.
Request
curl -X POST "https://www.hanghut.com/api/v1/tickets/a1b2c3d4-.../refund" \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"id": "a1b2c3d4-...",
"status": "refunded",
"event": { "id": "8db0f243-...", "title": "S10MAIC" },
"tier": { "name": "General Admission", "price": 1000 }
}
}/ordersPaginated purchase orders across all events. Filter by event_id.
Query Parameters
| page | integer | Page numberDefault: 1 |
| per_page | integer | Results per page (max 50) |
| event_id | uuid | Filter by event |
Request
curl "https://www.hanghut.com/api/v1/orders?event_id=8db0f243-..." \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"orders": [
{
"id": "9d13f49e-...",
"event": { "id": "bdb74865-...", "title": "Tinda Tindahan" },
"customer": {
"name": "Juan Dela Cruz",
"email": "juan@example.com",
"phone": "+639171234567"
},
"quantity": 1,
"total_amount": 720,
"subtotal": 700,
"status": "completed",
"payment_method": "GCASH",
"paid_at": "2026-03-30T08:44:12.267+00:00",
"created_at": "2026-03-30T08:39:23.276+00:00"
}
],
"meta": { "page": 1, "per_page": 20, "total": 32, "total_pages": 2, "has_more": true }
}
}Webhooks
Receive real-time notifications when events happen. Register an HTTPS endpoint and we'll POST signed payloads.
Available Events
| ticket.purchased | A ticket was purchased |
| ticket.refunded | A ticket was refunded |
| ticket.checked_in | A ticket was scanned |
| event.updated | Event details changed |
Each delivery includes an X-HangHut-Signature header (HMAC-SHA256) for verification.
Response
200{
"id": "evt_abc123...",
"type": "ticket.purchased",
"created_at": "2026-03-21T10:30:00Z",
"data": {
"ticket_id": "a1b2c3d4-...",
"event_id": "8db0f243-...",
"customer": { "name": "Juan Dela Cruz" },
"amount": 1000
}
}Verify Signature
# Webhook payloads are sent to YOUR endpoint. # Verify the X-HangHut-Signature header: # HMAC-SHA256(body, webhook_secret) === signature
/webhooksRegister a webhook endpoint. The response includes a secret for signature verification — save it, it's only shown once.
Request Body
| url | string | HTTPS endpoint URLREQUIRED |
| events | string[] | Event types to subscribe toREQUIRED |
Request
curl -X POST "https://www.hanghut.com/api/v1/webhooks" \
-H "Authorization: Bearer hh_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-site.com/webhook",
"events": ["ticket.purchased", "ticket.refunded"]
}'Response
201{
"data": {
"id": "wh_abc123...",
"url": "https://your-site.com/webhook",
"events": ["ticket.purchased", "ticket.refunded"],
"secret": "whsec_a1b2c3d4e5f6...",
"is_active": true
}
}/analytics/salesRevenue analytics with per-event breakdown. Optionally filter by event and date range.
Query Parameters
| event_id | uuid | Filter to specific event |
| from | ISO 8601 | Start of date range |
| to | ISO 8601 | End of date range |
Request
curl "https://www.hanghut.com/api/v1/analytics/sales?from=2026-03-01&to=2026-03-31" \ -H "Authorization: Bearer hh_live_your_key"
Response
200{
"data": {
"total_revenue": 11856.5,
"total_tickets_sold": 35,
"total_orders": 32,
"total_discounts": 285,
"date_range": { "from": null, "to": null },
"events": [
{
"id": "bdb74865-...",
"title": "Tinda Tindahan",
"start_datetime": "2026-04-14T11:07:00+00:00",
"capacity": 100,
"revenue": 4960,
"tickets_sold": 7,
"orders": 7,
"discount_total": 0
}
]
}
}/promo-codesCreate a promo code with percentage or fixed amount discounts, optional usage limits, and expiry.
Request Body
| event_id | uuid | Target eventREQUIRED |
| code | string | Promo code (min 3 chars)REQUIRED |
| discount_type | string | "percentage" or "fixed_amount"REQUIRED |
| discount_amount | number | Discount valueREQUIRED |
| usage_limit | integer | Max uses (unlimited if omitted) |
| expires_at | ISO 8601 | Expiry date |
Request
curl -X POST "https://www.hanghut.com/api/v1/promo-codes" \
-H "Authorization: Bearer hh_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"event_id": "8db0f243-...",
"code": "EARLYBIRD",
"discount_type": "percentage",
"discount_amount": 20,
"usage_limit": 50,
"expires_at": "2026-04-01T00:00:00Z"
}'Response
201{
"data": {
"id": "pc_abc123...",
"code": "EARLYBIRD",
"discount_type": "percentage",
"discount_amount": 20,
"usage_limit": 50,
"usage_count": 0,
"is_active": true
}
}Need help integrating? Contact support@hanghut.com
© 2026 HangHut. All rights reserved.