> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticketnation.ph/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete REST API endpoint documentation for the Ticketnation Open API.

## Base URL

```
https://api.ticketnation.ph/open-api/v1
```

All requests require the `api-key` header:

```
api-key: tn_live_your_key_here
```

## Response Format

All successful responses are wrapped in a `data` envelope. Paginated responses include a `meta` object:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "page": 1,
    "take": 10,
    "total": 42,
    "totalPages": 5
  }
}
```

Error responses use a consistent format:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event not found: abc-123",
    "hint": "Check that the event ID is correct and belongs to your organization."
  },
  "requestId": "req_a1b2c3d4"
}
```

<Info>
  Prices are in **whole pesos**, not centavos. `price: 1500` means **₱1,500.00**.
</Info>

***

## Account

### GET /me

Get information about the authenticated API key and its organization.

**Scope:** Any valid key

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/me \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": {
    "apiKey": {
      "id": "uuid",
      "name": "My Integration",
      "scopes": ["events:read", "events:write"],
      "callbackUrl": "https://api.partner.com/webhooks",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": "2025-03-15T12:00:00.000Z"
    },
    "organization": {
      "id": "uuid",
      "name": "Experia Events",
      "slug": "experia-events"
    }
  }
}
```

***

## Events

### POST /events

Create a new event in DRAFT status. Optionally include inline ticket types.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Music Fest",
    "dateTime": "2025-06-15T18:00:00.000Z",
    "endDateTime": "2025-06-15T23:00:00.000Z",
    "venueId": "uuid-venue-id",
    "imageUrl": "https://example.com/images/cover.jpg",
    "galleryUrls": [
      "https://example.com/images/gallery-1.jpg",
      "https://example.com/images/gallery-2.jpg"
    ],
    "absorbFees": true,
    "tickets": [
      {"name": "GA", "price": 1500, "quantity": 500, "published": true}
    ]
  }'
```

**Body parameters:**

| Field           | Type      | Required | Description                              |
| --------------- | --------- | -------- | ---------------------------------------- |
| `name`          | string    | Yes      | Event name                               |
| `dateTime`      | ISO 8601  | Yes      | Event start date/time                    |
| `endDateTime`   | ISO 8601  | No       | Event end date/time                      |
| `description`   | string    | No       | Event description                        |
| `type`          | enum      | No       | `PAID` (default) or `FREE`               |
| `journeyType`   | enum      | No       | `STANDARD`, `RSVP`, or `PRESELLING`      |
| `currency`      | string    | No       | `PHP` (default)                          |
| `locationType`  | enum      | No       | `VENUE` (default) or `ONLINE`            |
| `venueId`       | uuid      | No       | Venue ID (search via `/venues/search`)   |
| `imageUrl`      | string    | No       | Cover image URL for the event            |
| `galleryUrls`   | string\[] | No       | Array of gallery image URLs              |
| `eventCapacity` | number    | No       | Max attendees                            |
| `visibility`    | enum      | No       | `PUBLIC` (default) or `PRIVATE`          |
| `timezone`      | string    | No       | `Asia/Manila` (default)                  |
| `absorbFees`    | boolean   | No       | `true` (default) — include fees in price |
| `callbackUrl`   | string    | No       | Override webhook URL for this event      |
| `tickets`       | array     | No       | Inline ticket types (see Tickets)        |

### GET /events

List events for your organization.

**Scope:** `events:read`

**Query params:** `page`, `take`, `status` (DRAFT/PUBLISHED/ARCHIVED), `search`

```bash theme={null}
curl "https://api.ticketnation.ph/open-api/v1/events?status=PUBLISHED&page=1&take=10" \
  -H "api-key: tn_live_..."
```

### GET /events/:idOrSlug

Get event details by UUID or slug.

**Scope:** `events:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/summer-music-fest \
  -H "api-key: tn_live_..."
```

### PATCH /events/:id

Update event fields. Only provided fields are changed.

**Scope:** `events:write`

```bash theme={null}
curl -X PATCH https://api.ticketnation.ph/open-api/v1/events/{id} \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "eventCapacity": 2000,
    "imageUrl": "https://example.com/new-cover.jpg",
    "galleryUrls": ["https://example.com/gallery-new.jpg"]
  }'
```

### POST /events/:id/publish

Publish a DRAFT event to the marketplace.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{id}/publish \
  -H "api-key: tn_live_..."
```

### POST /events/:id/unpublish

Revert a PUBLISHED event to DRAFT.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{id}/unpublish \
  -H "api-key: tn_live_..."
```

### POST /events/:id/archive

Archive an event (hidden from marketplace, data preserved).

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{id}/archive \
  -H "api-key: tn_live_..."
```

### DELETE /events/:id

Delete a DRAFT event with no sold tickets.

**Scope:** `events:write`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/events/{id} \
  -H "api-key: tn_live_..."
```

***

## Tickets

All ticket endpoints are scoped to an event: `/events/:eventId/tickets`

### POST /events/:eventId/tickets

Create a ticket type. Individual ticket inventory is auto-generated.

**Scope:** `tickets:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Pass",
    "price": 5000,
    "quantity": 100,
    "section": "VIP Section",
    "published": true
  }'
```

**Body parameters:**

| Field                     | Type    | Required | Description                                  |
| ------------------------- | ------- | -------- | -------------------------------------------- |
| `name`                    | string  | Yes      | Ticket type name                             |
| `price`                   | number  | Yes      | Price in whole pesos (5000 = ₱5,000.00)      |
| `quantity`                | number  | Yes      | Total inventory                              |
| `section`                 | string  | No       | Section name (default: "General Admissions") |
| `row`                     | string  | No       | Row identifier (default: "GA")               |
| `type`                    | enum    | No       | `GENERAL_ADMISSION`, `RESERVED_SEAT`, `VIP`  |
| `maximumPurchaseQuantity` | number  | No       | Max per order (default: 8)                   |
| `published`               | boolean | No       | Available for sale immediately               |

### GET /events/:eventId/tickets

List all ticket types for an event.

**Scope:** `tickets:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets \
  -H "api-key: tn_live_..."
```

### GET /events/:eventId/tickets/:ticketId

Get ticket type details.

**Scope:** `tickets:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets/{ticketId} \
  -H "api-key: tn_live_..."
```

### PATCH /events/:eventId/tickets/:ticketId

Update a ticket type. Price and quantity changes are validated.

**Scope:** `tickets:write`

```bash theme={null}
curl -X PATCH https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets/{ticketId} \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"price": 4500, "quantity": 150}'
```

### POST /events/:eventId/tickets/:ticketId/publish

Make a ticket type available for purchase.

**Scope:** `tickets:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets/{ticketId}/publish \
  -H "api-key: tn_live_..."
```

### POST /events/:eventId/tickets/:ticketId/sold-out

Mark a ticket type as sold out (sets `remainingQuantity` to 0).

**Scope:** `tickets:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets/{ticketId}/sold-out \
  -H "api-key: tn_live_..."
```

### DELETE /events/:eventId/tickets/:ticketId

Delete a ticket type (only if no tickets sold).

**Scope:** `tickets:write`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/events/{eventId}/tickets/{ticketId} \
  -H "api-key: tn_live_..."
```

***

## Performers

Manage the performer lineup for an event. Performers can be linked to schedule entries.

All endpoints are scoped to an event: `/events/:eventId/performers`

### POST /events/:eventId/performers

Add a performer to an event.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/performers \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SB19",
    "type": "ARTIST",
    "imageUrl": "https://example.com/images/sb19.jpg",
    "description": "P-pop icons"
  }'
```

**Body parameters:**

| Field         | Type   | Required | Description                                              |
| ------------- | ------ | -------- | -------------------------------------------------------- |
| `name`        | string | Yes      | Performer name                                           |
| `type`        | string | No       | Performer type (e.g., `ARTIST`, `DJ`, `SPEAKER`, `HOST`) |
| `imageUrl`    | string | No       | URL to performer photo or logo                           |
| `description` | string | No       | Short bio or description                                 |

**Response:**

```json theme={null}
{
  "data": {
    "id": "uuid",
    "name": "SB19",
    "type": "ARTIST",
    "imageUrl": "https://example.com/images/sb19.jpg",
    "description": "P-pop icons",
    "eventId": "uuid",
    "createdAt": "2025-06-01T10:00:00.000Z"
  }
}
```

### GET /events/:eventId/performers

List all performers for an event.

**Scope:** `events:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/{eventId}/performers \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "name": "SB19",
      "type": "ARTIST",
      "imageUrl": "https://example.com/images/sb19.jpg",
      "description": "P-pop icons",
      "eventId": "uuid",
      "createdAt": "2025-06-01T10:00:00.000Z"
    }
  ]
}
```

### DELETE /events/:eventId/performers/:performerId

Remove a performer from an event.

**Scope:** `events:write`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/events/{eventId}/performers/{performerId} \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true,
    "id": "uuid"
  }
}
```

***

## Schedules

Build a timetable for your event with time slots that can be linked to performers.

All endpoints are scoped to an event: `/events/:eventId/schedules`

### POST /events/:eventId/schedules

Create a schedule entry.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/schedules \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SB19 Live",
    "startTime": "2025-06-15T20:00:00.000Z",
    "endTime": "2025-06-15T22:30:00.000Z",
    "description": "Main stage performance",
    "performerId": "uuid-performer-id",
    "color": "#1DB954",
    "icon": "microphone"
  }'
```

**Body parameters:**

| Field         | Type     | Required | Description                       |
| ------------- | -------- | -------- | --------------------------------- |
| `title`       | string   | Yes      | Schedule entry title              |
| `startTime`   | ISO 8601 | Yes      | Start time                        |
| `endTime`     | ISO 8601 | Yes      | End time                          |
| `description` | string   | No       | Details about this time slot      |
| `icon`        | string   | No       | Icon identifier for display       |
| `color`       | string   | No       | Hex color code (e.g., `#1DB954`)  |
| `performerId` | uuid     | No       | Link to a performer on this event |

**Response:**

```json theme={null}
{
  "data": {
    "id": "uuid",
    "title": "SB19 Live",
    "startTime": "2025-06-15T20:00:00.000Z",
    "endTime": "2025-06-15T22:30:00.000Z",
    "description": "Main stage performance",
    "performerId": "uuid-performer-id",
    "color": "#1DB954",
    "icon": "microphone",
    "eventId": "uuid",
    "createdAt": "2025-06-01T10:00:00.000Z"
  }
}
```

### GET /events/:eventId/schedules

List all schedule entries for an event.

**Scope:** `events:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/{eventId}/schedules \
  -H "api-key: tn_live_..."
```

### PATCH /events/:eventId/schedules/:scheduleId

Update a schedule entry. Only provided fields are changed.

**Scope:** `events:write`

```bash theme={null}
curl -X PATCH https://api.ticketnation.ph/open-api/v1/events/{eventId}/schedules/{scheduleId} \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SB19 Main Set (Extended)",
    "endTime": "2025-06-15T23:00:00.000Z"
  }'
```

### DELETE /events/:eventId/schedules/:scheduleId

Remove a schedule entry.

**Scope:** `events:write`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/events/{eventId}/schedules/{scheduleId} \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true,
    "id": "uuid"
  }
}
```

***

## Brands

Attach sponsor or partner brands to your event.

All endpoints are scoped to an event: `/events/:eventId/brands`

### POST /events/:eventId/brands

Add a brand to an event.

**Scope:** `events:write`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/events/{eventId}/brands \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Red Bull",
    "url": "https://redbull.com",
    "imageUrl": "https://example.com/images/redbull-logo.png",
    "description": "Energy drink partner"
  }'
```

**Body parameters:**

| Field         | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `name`        | string | Yes      | Brand name                           |
| `url`         | string | No       | Brand website URL                    |
| `imageUrl`    | string | No       | Logo URL                             |
| `description` | string | No       | Short description of the partnership |

**Response:**

```json theme={null}
{
  "data": {
    "id": "uuid",
    "name": "Red Bull",
    "url": "https://redbull.com",
    "imageUrl": "https://example.com/images/redbull-logo.png",
    "description": "Energy drink partner",
    "eventId": "uuid",
    "createdAt": "2025-06-01T10:00:00.000Z"
  }
}
```

### GET /events/:eventId/brands

List all brands for an event.

**Scope:** `events:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/events/{eventId}/brands \
  -H "api-key: tn_live_..."
```

### DELETE /events/:eventId/brands/:brandId

Remove a brand from an event.

**Scope:** `events:write`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/events/{eventId}/brands/{brandId} \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true,
    "id": "uuid"
  }
}
```

***

## Orders

### GET /events/:eventId/orders

List orders for an event.

**Scope:** `orders:read`

**Query params:** `page`, `take`, `status` (COMPLETED/PENDING/CANCELLED/REFUNDED)

```bash theme={null}
curl "https://api.ticketnation.ph/open-api/v1/events/{eventId}/orders?status=COMPLETED" \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "orderNumber": "TN-20250615-ABC123",
      "status": "COMPLETED",
      "totalAmount": 3000,
      "currency": "PHP",
      "quantity": 2,
      "buyerName": "Juan Dela Cruz",
      "buyerEmail": "juan@example.com",
      "eventId": "uuid",
      "orderItems": [
        {
          "id": "uuid",
          "quantity": 2,
          "price": 1500,
          "eventTicket": {
            "id": "uuid",
            "name": "General Admission",
            "section": "GA"
          }
        }
      ],
      "createdAt": "2025-06-15T18:30:00.000Z",
      "updatedAt": "2025-06-15T18:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "take": 10, "total": 1, "totalPages": 1 }
}
```

### GET /orders/:orderId

Get order details including payment info.

**Scope:** `orders:read`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/orders/{orderId} \
  -H "api-key: tn_live_..."
```

***

## Venues

### GET /venues/search

Search public venues by name. Use the returned `id` when creating events.

**Scope:** `events:read`

**Query params:** `query` (required), `page`, `take`

```bash theme={null}
curl "https://api.ticketnation.ph/open-api/v1/venues/search?query=MOA" \
  -H "api-key: tn_live_..."
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "name": "SM Mall of Asia Arena",
      "address1": "J.W. Diokno Blvd",
      "city": "Pasay City",
      "state": "Metro Manila",
      "country": "Philippines",
      "latitude": 14.5351,
      "longitude": 120.9832
    }
  ],
  "meta": { "page": 1, "take": 10, "total": 1, "totalPages": 1 }
}
```

***

## Webhooks

### POST /webhooks

Create a webhook endpoint. Returns a `secret` field — store it securely, it is only shown once.

**Scope:** `webhooks:manage`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/webhooks \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/ticketnation",
    "events": ["order.completed", "order.refunded", "event.sold_out", "ticket.inventory_low"]
  }'
```

**Body parameters:**

| Field    | Type      | Required | Description                                |
| -------- | --------- | -------- | ------------------------------------------ |
| `url`    | string    | Yes      | Your webhook endpoint URL (HTTPS required) |
| `events` | string\[] | Yes      | Array of event types to subscribe to       |

### GET /webhooks

List all webhooks.

**Scope:** `webhooks:manage`

```bash theme={null}
curl https://api.ticketnation.ph/open-api/v1/webhooks \
  -H "api-key: tn_live_..."
```

### PATCH /webhooks/:id

Update a webhook.

**Scope:** `webhooks:manage`

```bash theme={null}
curl -X PATCH https://api.ticketnation.ph/open-api/v1/webhooks/{id} \
  -H "api-key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"events": ["order.completed"], "isActive": true}'
```

### DELETE /webhooks/:id

Delete a webhook.

**Scope:** `webhooks:manage`

```bash theme={null}
curl -X DELETE https://api.ticketnation.ph/open-api/v1/webhooks/{id} \
  -H "api-key: tn_live_..."
```

### POST /webhooks/:id/test

Send a test event to verify your endpoint.

**Scope:** `webhooks:manage`

```bash theme={null}
curl -X POST https://api.ticketnation.ph/open-api/v1/webhooks/{id}/test \
  -H "api-key: tn_live_..."
```

### GET /webhooks/:id/deliveries

View delivery history for a webhook.

**Scope:** `webhooks:manage`

**Query params:** `page`, `take`

```bash theme={null}
curl "https://api.ticketnation.ph/open-api/v1/webhooks/{id}/deliveries?page=1&take=20" \
  -H "api-key: tn_live_..."
```