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

# Developer Overview

> Build on Ticketnation — publish events, sell tickets, and receive orders programmatically.

## What is the Ticketnation Open API?

The Open API lets third-party platforms integrate with Ticketnation's event ticketing marketplace. You can programmatically:

* **Publish events** with ticket types, venues, images, and pricing
* **Manage tickets** — update prices, quantities, and availability
* **Add performers** — attach artists, speakers, and acts to your events
* **Build schedules** — create timetables with time slots and performer links
* **Attach brands** — showcase sponsors and partners on your event page
* **Upload galleries** — add cover images and photo galleries to events
* **Receive orders** — read-only access to completed purchases
* **Search venues** — find existing venue IDs for your events
* **Set up webhooks** — get notified on `order.completed`, `order.refunded`, and more

All events created via the API appear on Ticketnation's consumer marketplace and mobile apps, giving your events instant access to Ticketnation's buyer network.

## Architecture

<Steps>
  <Step title="Your Platform">
    Your app sends requests to the Ticketnation Open API using the [ticketnation-sdk](https://www.npmjs.com/package/ticketnation-sdk) (TypeScript) or direct REST calls over HTTPS.
  </Step>

  <Step title="Ticketnation Open API">
    The API at `api.ticketnation.ph` processes your requests — creating events, managing tickets, attaching performers and schedules, and returning order data.
  </Step>

  <Step title="Ticketnation Marketplace">
    Published events appear instantly on the Ticketnation website and mobile apps, where buyers can discover and purchase tickets.
  </Step>

  <Step title="Webhooks (optional)">
    Ticketnation sends `order.completed`, `order.refunded`, `event.sold_out`, and `ticket.inventory_low` events to your webhook URL so you stay in sync.
  </Step>
</Steps>

<Note>
  The SDK is available on npm: [ticketnation-sdk v1.1.1](https://www.npmjs.com/package/ticketnation-sdk)
</Note>

## Two Ways to Integrate

<Tabs>
  <Tab title="TypeScript SDK (recommended)">
    Install the SDK from [npm](https://www.npmjs.com/package/ticketnation-sdk):

    ```bash theme={null}
    npm install ticketnation-sdk
    ```

    ```typescript theme={null}
    import { Ticketnation, formatPeso } from 'ticketnation-sdk';

    const tn = new Ticketnation({ apiKey: process.env.TICKETNATION_API_KEY! });

    // Create and publish in one call
    const event = await tn.events.createAndPublish({
      name: 'My Event',
      dateTime: '2025-06-15T18:00:00Z',
      tickets: [
        { name: 'GA', price: 1500, quantity: 500, published: true },
      ],
    });

    console.log(`Live! Ticket price: ${formatPeso(1500)}`);
    // Live! Ticket price: ₱1,500.00
    ```
  </Tab>

  <Tab title="REST API (any language)">
    Call the API directly with any HTTP client:

    ```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": "My Event", "dateTime": "2025-06-15T18:00:00Z"}'
    ```
  </Tab>
</Tabs>

## What You Can Build

<CardGroup cols={3}>
  <Card title="Events" icon="calendar">
    Create, update, publish, and manage the full event lifecycle
  </Card>

  <Card title="Tickets" icon="ticket">
    Define ticket types with pricing, quantities, and sections
  </Card>

  <Card title="Performers" icon="microphone">
    Add artists, speakers, and DJs to your event lineup
  </Card>

  <Card title="Schedules" icon="clock">
    Build timetables with time slots linked to performers
  </Card>

  <Card title="Brands" icon="star">
    Showcase sponsors and partners on your event page
  </Card>

  <Card title="Webhooks" icon="bell">
    Get real-time notifications for orders and inventory changes
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Get an API key">
    From your Organizer Dashboard under **Settings > API Keys**
  </Step>

  <Step title="Create events">
    Events start in `DRAFT` status with optional inline ticket types, or use `createAndPublish()` to go live immediately
  </Step>

  <Step title="Add tickets">
    Set pricing in whole pesos, quantities, and sections
  </Step>

  <Step title="Enrich your event">
    Add performers, schedules, brands, cover images, and gallery photos
  </Step>

  <Step title="Publish">
    The event goes live on the marketplace
  </Step>

  <Step title="Receive orders">
    Poll the orders endpoint or listen for `order.completed` webhooks
  </Step>

  <Step title="Get paid">
    Ticketnation handles payments and settles to your organization
  </Step>
</Steps>

## Pricing

Events created via the API use the same fee structure as organizer-created events:

<CardGroup cols={3}>
  <Card title="7% Commission" icon="percent">
    Platform commission on ticket sales
  </Card>

  <Card title="Processing Fees" icon="credit-card">
    Varies by payment method (GCash, card, etc.)
  </Card>

  <Card title="Absorb Fees" icon="toggle-on">
    Set `absorbFees: true` so buyers see the exact price you set
  </Card>
</CardGroup>

<Info>
  Prices are in **whole pesos**, not centavos. `price: 1500` means **₱1,500.00**. Use the `formatPeso()` utility to display prices correctly.
</Info>

## Rate Limits

| Tier       | Per Minute | Per Hour |
| ---------- | ---------- | -------- |
| Free       | 60         | 1,000    |
| Pro        | 300        | 5,000    |
| Enterprise | 1,000      | 20,000   |

Rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) are included in every response.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    Get from API key to a fully populated, published event in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/developers/authentication">
    API keys, scopes, and security
  </Card>

  <Card title="API Reference" icon="code" href="/developers/api-reference">
    Complete REST endpoint documentation
  </Card>

  <Card title="SDK Reference" icon="book" href="/developers/sdk-reference">
    TypeScript SDK methods, types, and utilities
  </Card>

  <Card title="MCP Server" icon="robot" href="/developers/mcp">
    Use the API from Claude, Cursor, or any MCP-compatible AI agent
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/developers/errors">
    Error codes, hints, and troubleshooting
  </Card>
</CardGroup>