HANGHUT
API Referencev1.0
Get API Key
API v1.0 — Live

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.

🔗RESTful JSON API
🔐Bearer token authentication
💳Hosted checkout (GCash, Maya, cards)
⚡100 requests/minute rate limit
🌐5 language SDKs (curl, JS, Python, PHP, Ruby)

Base URL

https://www.hanghut.com/api/v1

Endpoints

GET/events
GET/events/:id
POST/events
PUT/events/:id
GET/events/:id/attendees
POST/checkouts
GET/tickets/:id
POST/tickets/:id/check-in
POST/tickets/:id/refund
GET/orders
POST/webhooks
GET/analytics/sales
POST/promo-codes

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_.

Keep your keys secret. Never expose them in client-side code or public repositories.

Header

Authorization: Bearer hh_live_3dd28059a859bddb...

Example Request

cURL
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.

100
Requests
60s
Window
429
Exceeded

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.

CodeDescription
400Bad request — invalid parameters
401Unauthorized — bad or missing API key
404Not found
409Conflict — sold out or unavailable
429Rate limit exceeded
500Internal server error

Response

404
{
  "error": {
    "message": "Event not found",
    "status": 404
  }
}
GET/events

Returns a paginated list of events for your organization. Includes ticket tiers and real-time sold counts.

Query Parameters

pageintegerPage numberDefault: 1
per_pageintegerResults per page (max 50)Default: 20
statusstringFilter: active, draft, cancelledDefault: active

Request

cURL
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
    }
  }
}
GET/events/:id

Returns full event details including description, venue, images, and ticket tiers with real-time available counts per tier.

Path Parameters

iduuidEvent IDREQUIRED

Each tier includes an available field (quantity_total - quantity_sold).

Request

cURL
curl "https://www.hanghut.com/api/v1/events/8db0f243-2e64-..." \
  -H "Authorization: Bearer hh_live_your_key"
POST/events

Create a new event. Events are created in draft status by default.

Request Body

titlestringEvent nameREQUIRED
start_datetimeISO 8601Start date/timeREQUIRED
end_datetimeISO 8601End date/time
venue_namestringVenue name
citystringCity
capacityintegerMax attendees
ticket_pricenumberBase price in PHP

Request

cURL
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
  }
}
PUT/events/:id

Update event details. Only include fields you want to change. Set status to active to publish.

Request

cURL
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}'
GET/events/:id/attendees

Paginated list of attendees. Filter by ticket status for guest lists or export.

Query Parameters

pageintegerPage numberDefault: 1
per_pageintegerResults per page (max 100)
statusstringFilter: sold, checked_in, refunded

Request

cURL
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 }
  }
}
POST/checkouts

Creates a hosted checkout session. Redirect your customer to the returned URL to complete payment via GCash, Maya, bank transfer, or card.

Always use webhooks to confirm payment — the customer may close the browser before being redirected.

Request Body

event_iduuidEvent to buy tickets forREQUIRED
tier_iduuidTicket tier (default if omitted)
quantityintegerNumber of tickets (min 1)REQUIRED
customer.namestringCustomer full nameREQUIRED
customer.emailstringEmail for ticket deliveryREQUIRED
customer.phonestringPhone number
success_urlstringRedirect after paymentREQUIRED
cancel_urlstringRedirect if cancelled

Request

cURL
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"
  }
}
GET/tickets/:id

Verify a ticket's status, check-in state, and associated event/customer details.

Path Parameters

iduuidTicket IDREQUIRED

Ticket Statuses

soldValid, ready for check-in
checked_inAlready scanned
refundedRefunded
cancelledCancelled

Request

cURL
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"
    }
  }
}
POST/tickets/:id/check-in

Mark a ticket as checked in. Returns 409 if already used, refunded, or cancelled.

Build your own QR scanner — scan the ticket ID, call this endpoint, and show the result.

Request

cURL
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" }
  }
}
POST/tickets/:id/refund

Mark a ticket as refunded. Updates status and decrements sold count.

Note: This only updates the ticket status. The actual payment refund must be processed separately through your payment provider.

Request

cURL
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 }
  }
}
GET/orders

Paginated purchase orders across all events. Filter by event_id.

Query Parameters

pageintegerPage numberDefault: 1
per_pageintegerResults per page (max 50)
event_iduuidFilter by event

Request

cURL
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.purchasedA ticket was purchased
ticket.refundedA ticket was refunded
ticket.checked_inA ticket was scanned
event.updatedEvent 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

cURL
# Webhook payloads are sent to YOUR endpoint.
# Verify the X-HangHut-Signature header:
# HMAC-SHA256(body, webhook_secret) === signature
POST/webhooks

Register a webhook endpoint. The response includes a secret for signature verification — save it, it's only shown once.

Request Body

urlstringHTTPS endpoint URLREQUIRED
eventsstring[]Event types to subscribe toREQUIRED

Request

cURL
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
  }
}
GET/analytics/sales

Revenue analytics with per-event breakdown. Optionally filter by event and date range.

Query Parameters

event_iduuidFilter to specific event
fromISO 8601Start of date range
toISO 8601End of date range

Request

cURL
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
      }
    ]
  }
}
POST/promo-codes

Create a promo code with percentage or fixed amount discounts, optional usage limits, and expiry.

Request Body

event_iduuidTarget eventREQUIRED
codestringPromo code (min 3 chars)REQUIRED
discount_typestring"percentage" or "fixed_amount"REQUIRED
discount_amountnumberDiscount valueREQUIRED
usage_limitintegerMax uses (unlimited if omitted)
expires_atISO 8601Expiry date

Request

cURL
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.