{"openapi":"3.1.0","info":{"title":"Ayatickets Developer API","version":"1.0.0","description":"Official REST API for integrating Ayatickets event catalog, checkout, and order status into your applications. Use test keys (`ayt_test_*`) for sandbox mode. Live keys complete paid checkouts via hosted payment checkout; free orders complete immediately with `status: paid` and no `checkout_url`.","contact":{"name":"Ayatickets Developer Support","email":"developers@ayatickets.com","url":"https:\/\/developers.ayatickets.com\/reference"}},"servers":[{"url":"https:\/\/developers.ayatickets.com","description":"Production API"}],"tags":[{"name":"Events","description":"Read published events, dates, and ticket inventory."},{"name":"Checkout","description":"Create checkout sessions with idempotency support."},{"name":"Orders","description":"Retrieve order status for your checkouts."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Use `ayt_test_*` for sandbox or `ayt_live_*` for production."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"CheckoutSessionRequest":{"type":"object","required":["event_id","eventdate_id","items","customer","success_url","cancel_url"],"properties":{"event_id":{"type":"integer"},"eventdate_id":{"type":"integer"},"items":{"type":"array","items":{"type":"object","required":["ticket_id","quantity"],"properties":{"ticket_id":{"type":"integer"},"quantity":{"type":"integer","minimum":1,"maximum":50}}}},"customer":{"type":"object","required":["name","email","phone"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true}}},"EventPricingSummary":{"type":"object","properties":{"has_free_tickets":{"type":"boolean"},"has_paid_tickets":{"type":"boolean"},"is_entirely_free":{"type":"boolean"}}},"Event":{"type":"object","properties":{"id":{"type":"integer"},"reference":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"image_path":{"type":"string","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"active_dates_count":{"type":"integer"},"has_multiple_dates":{"type":"boolean"},"ussd_code":{"type":"string","nullable":true},"ussd_full_code":{"type":"string","nullable":true},"has_ussd":{"type":"boolean"},"next_startdate":{"type":"string","nullable":true},"last_enddate":{"type":"string","nullable":true},"next_startdate_iso":{"type":"string","format":"date-time","nullable":true},"last_enddate_iso":{"type":"string","format":"date-time","nullable":true},"next_startdate_display":{"type":"string","nullable":true},"last_enddate_display":{"type":"string","nullable":true},"timezone":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"pricing":{"$ref":"#\/components\/schemas\/EventPricingSummary"}}},"EventListMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_next":{"type":"boolean"},"has_prev":{"type":"boolean"},"timezone":{"type":"string"}}},"EventListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Event"}},"meta":{"$ref":"#\/components\/schemas\/EventListMeta"}}},"EventDetailResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Event"}}},"EventDate":{"type":"object","properties":{"id":{"type":"integer"},"reference":{"type":"string"},"event_id":{"type":"integer"},"startdate":{"type":"string"},"enddate":{"type":"string"},"startdate_iso":{"type":"string","format":"date-time","nullable":true},"enddate_iso":{"type":"string","format":"date-time","nullable":true},"startdate_display":{"type":"string","nullable":true},"enddate_display":{"type":"string","nullable":true},"online":{"type":"boolean"},"venue_id":{"type":"integer","nullable":true},"venue_name":{"type":"string","nullable":true},"venue_slug":{"type":"string","nullable":true},"venue_street":{"type":"string","nullable":true},"venue_city":{"type":"string","nullable":true},"venue_state":{"type":"string","nullable":true},"venue_lat":{"type":"number","nullable":true},"venue_lng":{"type":"number","nullable":true},"timezone":{"type":"string"}}},"EventDateListMeta":{"type":"object","properties":{"event_id":{"type":"integer"},"count":{"type":"integer"},"has_multiple_dates":{"type":"boolean"},"include_past":{"type":"boolean"},"timezone":{"type":"string"}}},"EventDateListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/EventDate"}},"meta":{"$ref":"#\/components\/schemas\/EventDateListMeta"}}},"Ticket":{"type":"object","properties":{"id":{"type":"integer"},"reference":{"type":"string"},"eventdate_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"free":{"type":"boolean"},"price":{"type":"string","nullable":true},"promotionalprice":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"quantity_available":{"type":"integer"},"ticketsperattendee":{"type":"integer","nullable":true},"salesstartdate":{"type":"string","nullable":true},"salesenddate":{"type":"string","nullable":true},"salesstartdate_iso":{"type":"string","format":"date-time","nullable":true},"salesenddate_iso":{"type":"string","format":"date-time","nullable":true},"currency":{"type":"string"},"currency_symbol":{"type":"string"},"is_free":{"type":"boolean"},"effective_price":{"type":"string"},"requires_payment":{"type":"boolean"},"timezone":{"type":"string"}}},"TicketListMeta":{"type":"object","properties":{"event_id":{"type":"integer"},"event_date_id":{"type":"integer"},"timezone":{"type":"string"}}},"TicketListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Ticket"}},"meta":{"$ref":"#\/components\/schemas\/TicketListMeta"}}},"CheckoutSessionResponse":{"type":"object","properties":{"order_reference":{"type":"string"},"checkout_url":{"type":"string","format":"uri","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["pending","paid"]},"environment":{"type":"string","enum":["test","live"]},"requires_payment":{"type":"boolean"},"total_amount":{"type":"string","nullable":true},"payment_reference":{"type":"string","nullable":true}}},"Order":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string","enum":["pending","paid","failed","expired","unknown"]},"status_code":{"type":"integer"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"payment_reference":{"type":"string","nullable":true},"environment":{"type":"string","enum":["test","live"]}}},"OrderResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Order"}}}},"headers":{"IdempotencyKey":{"description":"Unique key for safe checkout retries (required for POST \/checkout-sessions).","schema":{"type":"string","maxLength":128}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"\/api\/v1\/events":{"get":{"tags":["Events"],"summary":"List published events","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated event list","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EventListResponse"}}}},"401":{"description":"Invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/events\/{id}":{"get":{"tags":["Events"],"summary":"Get event details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Event object","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EventDetailResponse"}}}},"404":{"description":"Event not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/events\/{id}\/dates":{"get":{"tags":["Events"],"summary":"List event dates","description":"By default returns upcoming active dates only. Pass `include_past=true` to include dates whose end time has passed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"include_past","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Event dates","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EventDateListResponse"}}}},"404":{"description":"Event not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/event-dates\/{id}\/tickets":{"get":{"tags":["Events"],"summary":"List tickets for an event date","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Ticket inventory","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketListResponse"}}}},"404":{"description":"Event date not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/checkout-sessions":{"post":{"tags":["Checkout"],"summary":"Create a checkout session","description":"Test keys return a sandbox checkout URL (or immediate `paid` for free carts). Live paid orders return a hosted checkout URL. Live free orders complete immediately with `status: paid` and `requires_payment: false`.","parameters":[{"$ref":"#\/components\/headers\/IdempotencyKey","name":"Idempotency-Key","in":"header","required":true}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CheckoutSessionRequest"}}}},"responses":{"201":{"description":"Checkout session created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CheckoutSessionResponse"}}}},"400":{"description":"Missing idempotency key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Checkout unavailable","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/orders\/{reference}":{"get":{"tags":["Orders"],"summary":"Get order status","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order status","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderResponse"}}}},"403":{"description":"Environment mismatch","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Order not found for this app","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}}}