ticketnation-sdk

Official TypeScript SDK for the Ticketnation Open API. Publish events, manage tickets, receive orders, and search venues programmatically.

Installation

npm install ticketnation-sdk

Quick Start

import { Ticketnation} from 'ticketnation-sdk';

const tn = new Ticketnation({
  apiKey: 'tn_live_your_api_key_here',
});

// Create an event with tickets
const event = await tn.events.create({
  name: 'Summer Music Fest 2025',
  dateTime: '2025-06-15T18:00:00.000Z',
  venueId: 'uuid-venue-id',
  tickets: [
    { name: 'General Admission', price: 150000, quantity: 500 },
    { name: 'VIP', price: 500000, quantity: 50 },
  ],
});

// Publish it
await tn.events.publish(event.id);

Configuration

const tn = new Ticketnation({
  apiKey: 'tn_live_...',             // Required
  baseUrl: 'http://localhost:4000',  // Default: https://api.ticketnation.ph
  timeout: 30000,                    // Default: 30s
  retries: 2,                        // Default: 2 (retries on 5xx only)
  debug: false,                      // Default: false (logs redacted requests)
});

API Reference

Account

// Get API key info and organization details
const info = await tn.me();
// → { apiKey: { id, name, scopes, ... }, organization: { id, name, slug } }

Events

// Create
const event = await tn.events.create({ name: '...', dateTime: '...' });

// List (paginated)
const { data, meta } = await tn.events.list({ page: 1, take: 10, status: 'PUBLISHED' });

// Get by ID or slug
const event = await tn.events.get('summer-music-fest-2025');

// Update
const updated = await tn.events.update(eventId, { name: 'New Name' });

// Lifecycle
await tn.events.publish(eventId);
await tn.events.unpublish(eventId);
await tn.events.archive(eventId);

// Delete (DRAFT only, no sold tickets)
await tn.events.delete(eventId);

Tickets

// Create a ticket type for an event
const ticket = await tn.tickets.create(eventId, {
  name: 'VIP Pass',
  price: 500000,    // in centavos (5,000.00 PHP)
  quantity: 100,
});

// List all ticket types
const tickets = await tn.tickets.list(eventId);

// Get single ticket
const ticket = await tn.tickets.get(eventId, ticketId);

// Update price or quantity
await tn.tickets.update(eventId, ticketId, { price: 450000 });

// Publish (make available for sale)
await tn.tickets.publish(eventId, ticketId);

// Mark as sold out (sets remainingQuantity to 0)
await tn.tickets.markSoldOut(eventId, ticketId);

// Delete (only if no tickets sold)
await tn.tickets.delete(eventId, ticketId);

Orders

// List orders for an event (paginated)
const { data, meta } = await tn.orders.list(eventId, { page: 1, status: 'COMPLETED' });

// Get order details (includes line items and payment info)
const order = await tn.orders.get(orderId);

Venues

// Search venues by name
const { data, meta } = await tn.venues.search({ query: 'MOA Arena' });
// Use venue.id when creating events with locationType: 'VENUE'

Webhooks

// Create a webhook (secret is only returned once — store it!)
const webhook = await tn.webhooks.create({
  url: 'https://api.example.com/webhooks/ticketnation',
  events: ['order.completed', 'event.sold_out'],
});
console.log(webhook.secret); // whsec_...

// List all webhooks
const webhooks = await tn.webhooks.list();

// Update a webhook
await tn.webhooks.update(webhookId, { events: ['order.completed'] });

// Test a webhook (sends a test payload)
const result = await tn.webhooks.test(webhookId);

// View delivery history (paginated)
const { data, meta } = await tn.webhooks.deliveries(webhookId, { page: 1 });

// Delete a webhook
await tn.webhooks.delete(webhookId);

Pagination Helper

For iterating through all pages automatically:

import { Ticketnation, paginate, fetchAllPages } from 'ticketnation-sdk';

const tn = new Ticketnation({ apiKey: '...' });

// Async iterator — processes one page at a time
for await (const batch of paginate((p) => tn.events.list(p))) {
  console.log(`Got ${batch.length} events`);
}

// Fetch all at once
const allEvents = await fetchAllPages((p) => tn.events.list(p));

Error Handling

All API errors throw TicketnationError with structured details:

import { Ticketnation, TicketnationError } from 'ticketnation-sdk';

try {
  await tn.events.get('nonexistent');
} catch (error) {
  if (error instanceof TicketnationError) {
    console.log(error.code);      // 'NOT_FOUND'
    console.log(error.status);    // 404
    console.log(error.message);   // 'Event not found: nonexistent'
    console.log(error.requestId); // 'req_a1b2c3d4' (for support)
  }
}

Error Codes

| Code | Status | Description | |------|--------|-------------| | VALIDATION_ERROR | 400 | Invalid input — check error.details for field-level errors | | UNAUTHORIZED | 401 | Missing or invalid API key | | FORBIDDEN | 403 | API key lacks required scope | | NOT_FOUND | 404 | Resource not found or not owned by your organization | | RATE_LIMITED | 429 | Too many requests — SDK auto-retries on 5xx, not 429 | | INTERNAL_ERROR | 500 | Server error — SDK auto-retries up to retries times | | TIMEOUT | 0 | Request exceeded timeout ms | | NETWORK_ERROR | 0 | DNS, connection, or other network failure |

Scopes

Your API key needs the right scopes for each operation:

| Scope | Operations | |-------|------------| | events:read | List/get events, search venues | | events:write | Create/update/publish/delete events | | tickets:read | List/get tickets | | tickets:write | Create/update/publish/delete/sold-out tickets | | orders:read | List/get orders | | webhooks:manage | Create/update/delete webhooks |

Authentication

Get your API key from Organizer Dashboard > Settings > API Keys.

The SDK sends the key via the api-key HTTP header. Keys are scoped to a single organization.

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5.0+ (optional but recommended)

Full Documentation

For complete REST API reference with curl examples, webhook setup, and architecture overview, visit the Ticketnation Developer Docs.

License

MIT