{"openapi":"3.1.0","info":{"title":"AXYN Ticketing API","version":"1.0.0","description":"Standalone AXYN ticketing platform API.\n\n## Authentication\n\nThree schemes are used:\n\n- **`x-api-key`**: per-tenant API key (with scopes) for server-to-server catalog/integration calls. Use `axyn_sk_test_...` keys for sandbox data and `axyn_sk_live_...` keys for live data on the same API host.\n- **`Authorization: Bearer`**: Supabase-issued user JWT for end-user and staff actions.\n- **`x-scanner-token`**: scanner device token for hosted/offline scanning.\n\nMost write endpoints on `/v1/orders` require an **`Idempotency-Key`** header. Scan endpoints return business outcomes in the response body (`result_code`) with HTTP 200; only transport/validation failures use 4xx/5xx.\n\n## Quickstart\n\n1. Mint a scoped test tenant API key (`x-api-key`) in Admin Developer settings.\n2. **Browse the catalog**: `GET /v1/events/{eventId}/tiers` (`catalog:read`).\n3. **Create an order**: `POST /v1/orders` with an `Idempotency-Key` header (Supabase JWT).\n4. **Pay**: complete the Stripe PaymentIntent client secret returned when payment is started. Test keys return Stripe test-mode client secrets.\n5. **Scan at the door**: `POST /v1/tickets/scan` (staff JWT) or `POST /v1/tickets/validate` (scanner device token).\n\n## Required disclosure\n\nEvery buyer checkout must show AXYN's privacy notice where the buyer enters their details or card (the notice at the point of collection that CCPA requires): the text `Ticketing by AXYN · Privacy`, with `Privacy` linking to `https://axyn.events/legal/privacy`. The Web SDK renders it in every checkout. API-only integrations must render it themselves, on every step that collects buyer details or a card, including cash-at-the-door and free orders.\n\nThe machine-readable contract is at `/openapi.json` and a Postman collection at `/postman_collection.json`.","license":{"name":"Proprietary"}},"servers":[{"url":"https://api.axyn.events","description":"Production API host. Sandbox uses this host with an axyn_sk_test_ key."},{"url":"http://localhost:4001","description":"Local development"}],"tags":[{"name":"health","description":"Liveness / readiness probes (no auth)."},{"name":"discovery","description":"Cross-tenant discovery feed over the discovery_event projection (tenant API key + discovery:read)."},{"name":"tenants","description":"Self-serve organizer tenant signup and membership discovery (Supabase JWT, non-anonymous)."},{"name":"catalog","description":"Public catalog reads (tenant API key + catalog:read)."},{"name":"checkout","description":"Order creation, payment start, order read (Supabase JWT)."},{"name":"seats","description":"Reserved-seat holds (Supabase JWT)."},{"name":"tickets","description":"End-user ticket reads (Supabase JWT)."},{"name":"scanning","description":"Scanner-token issuance, online/offline scan, manifest."},{"name":"connect","description":"Stripe Connect onboarding for producers (organizer JWT + tenant_staff organizer_admin, or super_admin bypass; optional x-api-key must match path tenant)."},{"name":"webhooks","description":"Inbound Stripe webhook (signature-verified, no bearer)."},{"name":"buyer","description":"End-user (buyer) self-serve — Supabase JWT."},{"name":"notifications","description":"Buyer notification preferences (Supabase JWT)."},{"name":"transfers","description":"Buyer-initiated ticket transfer offers + recipient claims."},{"name":"vouchers","description":"Voucher redemption + organizer void."},{"name":"federation","description":"Partner token exchange (RFC 8693): a registered, allowlisted partner trades its user token for an AXYN buyer session (no bearer)."},{"name":"public","description":"Credential-free public endpoints (bearer-token in path, or open intake with rate limits)."},{"name":"ticket-lifecycle","description":"Organizer-driven ticket lifecycle (void, comp-exchange, reissue, voucher-swap)."},{"name":"refunds","description":"Buyer refund requests + eligibility (Supabase JWT)."},{"name":"photos","description":"Event photos: buyer views + organizer uploads + removal requests."},{"name":"consents","description":"Marketing consent + cross-organizer recommendations (Supabase JWT)."},{"name":"event-lifecycle","description":"Event cancellation + draft preview tokens (organizer surfaces)."},{"name":"estate-claims","description":"Public estate-claim intake (D12.1 buyer death / estate handling)."},{"name":"account-recovery","description":"Public account-recovery request intake (D12.3 identity stolen)."},{"name":"fraud-claims","description":"Authenticated fraud-claim intake (D12.10 stolen ticket)."},{"name":"group-sales","description":"Above-cap group-sales request intake (public)."},{"name":"upgrades","description":"Guest-first and signed-in ticket upgrades, plus organizer path CRUD. Same Live Pass URL after pay."},{"name":"accreditation","description":"ENG-1591 accreditation classes and applications"}],"security":[],"components":{"securitySchemes":{"tenantApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Per-tenant API key. Scopes: catalog:read, orders:read, orders:write, tickets:read, scan:write, payments:attest and client_ip:attest (platform-granted only; never self-serve), or * (wildcard, cannot combine with explicit scopes). A key holding client_ip:attest may name the buyer it calls for in X-Axyn-Client-IP; per-IP limits then count that buyer instead of the calling server. Without the scope the header is ignored."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase-issued user JWT. Some routes additionally require a staff/admin role."},"scannerToken":{"type":"apiKey","in":"header","name":"x-scanner-token","description":"Opaque scanner device token (scn_...) scoped to a venue_event; issued via POST /v1/tickets/scanner-tokens."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Client-generated idempotency key, 8-128 characters.","schema":{"type":"string","minLength":8,"maxLength":128}},"PreviousEditionFor":{"name":"previous_edition_for","in":"query","required":false,"description":"ENG-2417 C2, staff only (403 `previous_edition_staff_only` otherwise). With an event id (on `/v1/events`) or a series id (on `/v1/productions`), `data` is `{ editions: PickableEdition[] }` instead of the list: every edition of the organization that id may link to as its previous edition, newest first, judged by the same rule as the update (never itself, a draft, one not yet held, one that already follows it, or a show inside a series). 404 `edition_not_found` when the id is not the organization's. The list's other query parameters are ignored.","schema":{"type":"string","format":"uuid"}},"TenantIdHeader":{"name":"x-tenant-id","in":"header","required":false,"description":"Organizer tenant UUID. Required for staff JWT calls to partner catalog routes (`/v1/events*`). When `x-api-key` is present, must match the key tenant if sent.","schema":{"type":"string","format":"uuid"}},"AccessCodeHeader":{"name":"X-Axyn-Access-Code","in":"header","required":false,"description":"Unlocks a named house hold at the listed price. Header only so the code is not stored in URLs, Referer, or history.","schema":{"type":"string"}}},"schemas":{"TenantOrderShow":{"type":"object","description":"ENG-3035. The show a ticket admits to: its start (UTC) and the show's time zone, which in a series is the series' zone. `room` is the show's venue name.","required":["event_id","title","starts_at","timezone","room"],"properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"timezone":{"type":"string","nullable":true},"room":{"type":"string","nullable":true}}},"TenantOrderSeat":{"type":"object","required":["section","row","number","label"],"properties":{"section":{"type":"string","nullable":true},"row":{"type":"string"},"number":{"type":"string"},"label":{"type":"string","nullable":true}}},"TenantOrderLine":{"type":"object","description":"ENG-3035. One line per ticket type and show in the order. A pass has no `show` (it spans shows) and carries its coverage instead.","required":["ticket_tier_id","name","quantity","kind","unit_price_cents","show","seats","pass_coverage","pass_coverage_days"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"quantity":{"type":"integer"},"kind":{"type":"string","enum":["day","pass"]},"unit_price_cents":{"type":"integer"},"show":{"allOf":[{"$ref":"#/components/schemas/TenantOrderShow"}],"nullable":true},"seats":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderSeat"}},"pass_coverage":{"type":"string","enum":["shows","all","days"],"nullable":true},"pass_coverage_days":{"type":"array","items":{"type":"string","format":"date"}}}},"TenantOrderAddOn":{"type":"object","required":["add_on_id","name","quantity","unit_price_cents"],"properties":{"add_on_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"quantity":{"type":"integer"},"unit_price_cents":{"type":"integer"}}},"TenantOrderDisplayFacts":{"type":"object","description":"ENG-3035. `order_reference` is the 8-character number buyers read back (first 8 of the id, uppercased). `display_status` is the one status an organizer reads; `cancelled` covers an order never paid (cancelled, failed or expired hold). `paid_with` is the wallet or card the buyer used (null on cash and bank). `sold_at_door` marks a sale staff made at the door.","required":["order_reference","display_status","paid_with","sold_at_door"],"properties":{"order_reference":{"type":"string"},"display_status":{"type":"string","enum":["paid","pending","refunded","partially_refunded","cancelled"]},"paid_with":{"type":"string","enum":["card","apple_pay","google_pay","link","other"],"nullable":true},"paid_card_brand":{"type":"string","nullable":true,"description":"ENG-3036. Card brand Stripe reported for the charge (visa, mastercard, amex, …), wallets included."},"paid_card_last4":{"type":"string","nullable":true,"description":"ENG-3036. The last 4 Stripe reports for the card. For a wallet it may differ from the number printed on the card. Null for a viewer."},"paid_bank_name":{"type":"string","nullable":true,"description":"ENG-3036. Bank of a US bank account payment. Null for a viewer."},"paid_bank_last4":{"type":"string","nullable":true,"description":"ENG-3036. Last 4 of that bank account. Null for a viewer."},"sold_at_door":{"type":"boolean"}}},"TenantOrderListRow":{"allOf":[{"$ref":"#/components/schemas/TenantOrderDisplayFacts"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"payment_method":{"type":"string","enum":["card","apple_pay","google_pay","cash_at_entry","ach"]},"currency":{"type":"string"},"subtotal_cents":{"type":"integer"},"fees_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"purchaser_email":{"type":"string","nullable":true,"description":"Masked for a viewer."},"purchaser_name":{"type":"string","nullable":true,"description":"Null for a viewer."},"purchaser_phone":{"type":"string","nullable":true,"description":"Null for a viewer."},"qty":{"type":"integer"},"venue_event_id":{"type":"string"},"stripe_payment_intent_id":{"type":"string","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"production_id":{"type":"string","format":"uuid","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderLine"}},"add_ons":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderAddOn"}},"event_title":{"type":"string","nullable":true,"description":"ENG-3037. Title of the event the order was bought for."},"series_title":{"type":"string","nullable":true,"description":"ENG-3037. Title of the series it was sold under; null outside a series."}}}]},"TenantOrderDrillTicket":{"type":"object","description":"ENG-3035. A ticket with its current holder (`guest_*`), who passed it on (`passed_on_from`), its show and seat. Names are null and emails masked for a viewer.","properties":{"id":{"type":"string","format":"uuid"},"ticket_number":{"type":"string"},"ticket_tier_id":{"type":"string","format":"uuid"},"tier_name":{"type":"string"},"kind":{"type":"string","enum":["day","pass"]},"status":{"type":"string"},"transfer_status":{"type":"string"},"refund_status":{"type":"string"},"refund_amount_cents":{"type":"integer"},"redeemed_at":{"type":"string","format":"date-time","nullable":true},"purchase_price_cents":{"type":"integer"},"total_paid_cents":{"type":"integer"},"guest_first_name":{"type":"string","nullable":true},"guest_last_name":{"type":"string","nullable":true},"guest_email":{"type":"string","nullable":true},"passed_on_from":{"type":"object","nullable":true,"properties":{"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"at":{"type":"string","format":"date-time"}}},"show":{"allOf":[{"$ref":"#/components/schemas/TenantOrderShow"}],"nullable":true},"seat":{"allOf":[{"$ref":"#/components/schemas/TenantOrderSeat"}],"nullable":true},"refund_withheld_reason":{"type":"string","nullable":true,"description":"ENG-3040. Why this ticket cannot be refunded to the guest (`ticket_redeemed`, `ticket_superseded`, `ticket_transferred`), from the one refund rule."},"refund_quote_cents":{"type":"integer","nullable":true,"description":"ENG-3040. What refunding this ticket now returns, by AXYN's voluntary refund rules (fees kept). Null when it cannot be refunded."},"missing_answer_count":{"type":"integer","description":"ENG-3041. Required questions of the ticket's show it has no answer to, for example after a change of show to a show that asks something new."}}},"TenantOrderDrill":{"type":"object","description":"ENG-3035. One order as the order panel shows it. `money` is the order's money from the same computation as the Overview (`you_keep_cents` and its parts); null only before the order is priced.","properties":{"order":{"allOf":[{"$ref":"#/components/schemas/TenantOrderDisplayFacts"},{"type":"object","additionalProperties":true}]},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderDrillTicket"}},"event_title":{"type":"string","nullable":true,"description":"ENG-3037. Title of the event the order was bought for."},"series_title":{"type":"string","nullable":true,"description":"ENG-3037. Title of the series it was sold under; null outside a series."},"refund_requests":{"type":"array","items":{"type":"object","additionalProperties":true}},"payments":{"type":"array","items":{"type":"object","additionalProperties":true}},"lines":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderLine"}},"add_ons":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderAddOn"}},"sessions":{"type":"array","description":"Sessions a pass in the order saved a seat for.","items":{"type":"object","properties":{"ticket_id":{"type":"string","format":"uuid"},"show":{"$ref":"#/components/schemas/TenantOrderShow"},"status":{"type":"string"},"claimed_at":{"type":"string","format":"date-time","nullable":true}}}},"upgrades":{"type":"array","description":"Upgrades paid after purchase: the amount charged and when.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ticket_id":{"type":"string","format":"uuid"},"from_tier_name":{"type":"string","nullable":true},"to_tier_name":{"type":"string","nullable":true},"amount_cents":{"type":"integer"},"completed_at":{"type":"string","format":"date-time"}}}},"tier_moves":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ticket_id":{"type":"string","format":"uuid"},"from_tier_name":{"type":"string","nullable":true},"to_tier_name":{"type":"string","nullable":true},"reason":{"type":"string"},"moved_by_user_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"from_show":{"description":"ENG-3041. The show the old ticket type is on; differs from `to_show` for a change of show.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TenantOrderShow"}]},"to_show":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/TenantOrderShow"}]}}}},"show_move_targets":{"type":"array","description":"ENG-3041. For each ticket type on a series order, the other shows of the series a ticket can move to (same price, on sale, not started), with how many tickets fit now. Empty unless the caller may move tickets (`ticket.tier_move`); an event-scoped caller sees only shows it manages.","items":{"type":"object","properties":{"source_tier_id":{"type":"string","format":"uuid"},"targets":{"type":"array","items":{"type":"object","properties":{"tier_id":{"type":"string","format":"uuid"},"tier_name":{"type":"string"},"event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"timezone":{"type":"string","nullable":true},"room":{"type":"integer","description":"Tickets that fit now: the type's remaining, capped by the show's capacity."}}}}}}},"coupons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"discount_cents":{"type":"integer"}}}},"source":{"type":"object","nullable":true,"description":"Where the order was bought, as checkout recorded it.","properties":{"surface":{"type":"string","nullable":true},"integration":{"type":"string","nullable":true},"host":{"type":"string","nullable":true},"referrer_host":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"tracking_link_id":{"type":"string","format":"uuid","nullable":true},"tracking_link_name":{"type":"string","nullable":true},"utm_source":{"type":"string","nullable":true},"utm_medium":{"type":"string","nullable":true},"utm_campaign":{"type":"string","nullable":true}}},"answers":{"type":"array","description":"Checkout answers as the buyer saw each question. Empty for a viewer.","items":{"type":"object","properties":{"question_id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"answer_text":{"type":"string","nullable":true},"answer_yes_no":{"type":"boolean","nullable":true}}}},"cash":{"type":"object","nullable":true,"description":"Cash at the door: what was expected, collected, when and by which staff member.","properties":{"status":{"type":"string"},"expected_amount_cents":{"type":"integer"},"collected_amount_cents":{"type":"integer","nullable":true},"collected_at":{"type":"string","format":"date-time","nullable":true},"collected_by_user_id":{"type":"string","format":"uuid","nullable":true}}},"staff_names":{"type":"array","description":"Names of this organization's staff the order names (cash collector, movers, refund reviewers).","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"money":{"type":"object","nullable":true,"additionalProperties":{"type":"integer"},"properties":{"you_keep_cents":{"type":"integer"},"refunds_cents":{"type":"integer"},"payout_cents":{"type":"integer"},"addon_fee_cents":{"type":"integer","description":"ENG-3320. The add-on fee charged on this order (snapshot at purchase), part of the AXYN fee figure, shown as its own line under its name."},"organizer_addon_fee_cents":{"type":"integer","description":"ENG-3320. The part of addon_fee_cents the organizer covers (a fee you cover, out of You keep)."}}}}},"EventBudgetLine":{"type":"object","required":["category","amount_cents"],"properties":{"category":{"type":"string","enum":["artists_and_talent","venue","production_and_equipment","staff","marketing","other"]},"amount_cents":{"type":"integer","minimum":0,"maximum":100000000000},"note":{"type":["string","null"],"maxLength":200}}},"EventBudgetInput":{"type":"object","required":["lines"],"description":"ENG-2408 C1 and C2. The event's or series' cost budget: at most one line per category; the lines replace the stored ones and an empty list removes the budget. Organizer admin, finance and event manager may send it (staff JWT only; a tenant API key gets 403 `budget_requires_staff`). A finance user's update may carry only this field. An AXYN super admin must send `reason` (400 `budget_reason_required`), recorded with the change. A show inside a series has no budget of its own (409 `budget_set_on_series`); the budget takes the one currency the event or series sells in (409 `budget_currency_mixed` when it sells in several).","properties":{"lines":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/EventBudgetLine"}},"reason":{"type":["string","null"],"maxLength":500,"description":"Required from an AXYN super admin."}}},"EventBudgetRead":{"type":"object","required":["status"],"description":"ENG-2408 C2. `set`: the lines, their live total and currency (organizer admin, finance, event manager, super admin). `none`: no costs entered. `masked`: another staff role that reads the Overview; no amounts. Left out for a tenant API key and roles that never see costs.","properties":{"status":{"type":"string","enum":["set","none","masked"]},"currency":{"type":"string"},"total_cents":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/EventBudgetLine"}},"updated_at":{"type":"string","format":"date-time"}}},"SalesBreakEven":{"type":"object","required":["status"],"description":"ENG-2408 C2 to C11. You get (after fees and refunds) against the budget's total costs, from the money module; `projection` from the forecast. `masked`: a role without costs. `no_costs`: offer \"Add your costs\". `mixed_currency`: break-even needs sales in one currency. `unavailable`: could not be read.","properties":{"status":{"type":"string","enum":["masked","no_costs","mixed_currency","unavailable","computed"]},"currency":{"type":"string"},"costs_cents":{"type":"integer"},"you_get_cents":{"type":"integer"},"percent":{"type":"integer","description":"Whole percent of costs covered, never below 0; over 100 once passed."},"to_go_cents":{"type":"integer"},"passed_by_cents":{"type":"integer"},"keep_per_ticket_cents":{"type":["integer","null"]},"tickets_to_go":{"type":["integer","null"]},"sell_out_short_cents":{"type":["integer","null"],"description":"C7: still short after selling every remaining ticket at today's keep per ticket; 0 when selling out covers it; null with no ceiling or once passed."},"projection":{"type":["object","null"],"description":"C5 and C6: `passes` with the forecast day it passes, or `short` with what is still missing at the likely finish; null with no forecast.","properties":{"kind":{"type":"string","enum":["passes","short"]},"day":{"type":"string","format":"date"},"short_cents":{"type":"integer"}}}}},"SalesLeadTime":{"type":"object","description":"ENG-2408 B5. Days before the event (a series: its last show) by which half the paid tickets sold. `last_run_days`: the organizer's last finished event (or series), null when none.","properties":{"this_run_days":{"type":"integer"},"last_run_days":{"type":["integer","null"]}}},"PickableEdition":{"type":"object","description":"ENG-2417 C2. One edition the picker may offer (`previous_edition_for`). Organizer only.","required":["id","title","state","first_starts_at","last_starts_at","previous_id","in_series","timezone","venue_ids"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"state":{"type":"string","enum":["held","cancelled"]},"first_starts_at":{"type":["string","null"],"format":"date-time"},"last_starts_at":{"type":["string","null"],"format":"date-time"},"previous_id":{"type":["string","null"],"format":"uuid"},"in_series":{"type":"boolean"},"timezone":{"type":["string","null"]},"venue_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"SalesLastYear":{"type":"object","description":"ENG-2417 A9. This event or series against its previous edition at the same number of days before the show: paid tickets bought by then and still held (comps and test orders excluded; a series counts its tickets and passes). Tickets only, never money. Null on the dashboard with no link, a show inside a series, or a previous edition with no paid tickets.","required":["label_year","cancelled_years","phase","this_sold","this_capacity","last_at_point","last_capacity","last_final","onsale_shift_days"],"properties":{"label_year":{"type":["integer","null"],"description":"The compared edition's show year when it is not about a year earlier (10 to 14 months); null: \"Last year\"."},"cancelled_years":{"type":"array","items":{"type":"integer"},"description":"Years of cancelled editions skipped to reach the compared one."},"phase":{"type":"string","enum":["selling","finished"]},"this_sold":{"type":"integer"},"this_capacity":{"type":["integer","null"]},"last_at_point":{"type":["integer","null"],"description":"Null when last year's sales had not opened by this point."},"last_capacity":{"type":["integer","null"]},"last_final":{"type":"integer"},"onsale_shift_days":{"type":["integer","null"],"description":"Days this year's sales opened later (positive) or earlier (negative) before the show."}}},"TicketsPerOrderShare":{"type":"object","description":"ENG-2408 B6. Paid orders, and those for 2 or more tickets (the tickets-per-order rule Suggested moves uses).","properties":{"orders_count":{"type":"integer"},"orders_2_plus_count":{"type":"integer"},"share_2_plus":{"type":["number","null"]}}},"SummaryCadence":{"type":"string","enum":["off","daily","weekly"],"description":"ENG-2404: the Overview summary email cadence. Weekly sends Mondays at 08:00 in the event's time zone for the last full week; Daily every morning at 08:00. Off sends nothing."},"SummaryUnsubscribeView":{"type":"object","required":["title","org_name","cadence"],"properties":{"title":{"type":"string","description":"The event or series the subscription covers."},"org_name":{"type":"string","description":"The organizer's display name (the email's sender)."},"cadence":{"$ref":"#/components/schemas/SummaryCadence"}}},"SummarySubscription":{"type":"object","required":["scope","id","cadence"],"properties":{"scope":{"type":"string","enum":["event","series"]},"id":{"type":"string","format":"uuid","description":"The native event id, or the series (production) id."},"cadence":{"$ref":"#/components/schemas/SummaryCadence"}}},"SummarySubscriptionListItem":{"allOf":[{"$ref":"#/components/schemas/SummarySubscription"},{"type":"object","required":["title"],"properties":{"title":{"type":"string"}}}]},"SalesForecastDay":{"type":"object","required":["day","units"],"properties":{"day":{"type":"string","format":"date","description":"Calendar day in the event's time zone."},"units":{"type":"integer"}}},"SalesForecastReason":{"type":"string","enum":["not_on_sale","event_cancelled","no_sales_yet","off_sale","sales_closed","unavailable"],"description":"Why there is no forecast (sales_closed: the type's sale ended, its finish is what it sold; unavailable: it could not be computed, the rest of the dashboard still answers)."},"SalesForecastCurrencyGross":{"type":"object","required":["currency","gross_so_far_cents","likely_finish_gross_cents","range_low_gross_cents","range_high_gross_cents","gross_this_week_cents","gross_prev_week_cents"],"properties":{"currency":{"type":"string"},"gross_so_far_cents":{"type":"integer"},"likely_finish_gross_cents":{"type":["integer","null"]},"range_low_gross_cents":{"type":["integer","null"]},"range_high_gross_cents":{"type":["integer","null"]},"gross_this_week_cents":{"type":"integer"},"gross_prev_week_cents":{"type":"integer"}}},"SalesForecast":{"type":"object","description":"ENG-2399 sales forecast for a run or one ticket/pass type.","required":["unlimited","capacity","capacity_total","held","comped","target","sold","path","band_low","band_high","likely_finish","range_low","range_high","range_method","demand_p50_uncapped","demand_p90_uncapped","forecast_reason_detail","at_this_pace","sell_out_date","sell_out_from","sell_out_to","pace","pace_14d","needed_pace","vs_path","status","forecast_daily","pace_short","sold_out","sold_out_at","reopened_units","currency","live_price_cents","gross_so_far_cents","likely_finish_gross_cents","range_low_gross_cents","range_high_gross_cents","gross_this_week_cents","gross_prev_week_cents","gross_by_currency","method","own_weight","model_version","basis","path_gross_cents","band_low_gross_cents","band_high_gross_cents","forecast_daily_gross_cents","vs_path_gross_cents","compare_from"],"properties":{"unlimited":{"type":"boolean","description":"No capacity anywhere (inventory 0 and no area pool; AXYN has no unlimited flag): pace and at_this_pace only, no path, range or sell-out."},"capacity":{"type":["integer","null"],"description":"Sellable capacity: total minus held and comped. Null when unlimited."},"capacity_total":{"type":["integer","null"],"description":"Total capacity (area pools once)."},"held":{"type":"integer","description":"Remaining comp and named holds (the one-house Held), which could be released."},"comped":{"type":"integer","description":"Comps issued."},"target":{"type":["integer","null"],"description":"Where the path ends: a series goal, else sellable capacity."},"sold":{"type":"integer","description":"Paid tickets still held (refunds, cancellations, voids and chargebacks drop out; comps never count; orders excluded from reporting never count)."},"path":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastDay"},"description":"Typical cumulative paid tickets per day from on-sale to the (last) show, scaled to the target. The shape: own comparable completed runs partially pooled with anonymous similar runs (weight own = n/(n+5)), else a fixed default curve. Never a straight line. A capacity edit rescales the path from today; earlier days keep the logged target."},"band_low":{"type":["array","null"],"items":{"type":"integer"},"description":"Normal range under the path (25th percentile), index-aligned. Null on the default curve and for every type."},"band_high":{"type":["array","null"],"items":{"type":"integer"},"description":"Normal range over the path (75th percentile)."},"likely_finish":{"type":["integer","null"],"description":"Most likely final paid tickets: 7-day pace along the path blended 50/50 with the path's remaining share. Never below sold, never above capacity. Null with forecast_reason_detail not_enough_data_yet (under 3 days of sales on the default curve)."},"range_low":{"type":["integer","null"],"description":"Low end of the finish."},"range_high":{"type":["integer","null"],"description":"High end of the finish."},"range_method":{"type":["string","null"],"enum":["past_runs_10_90","spread_of_past_runs","similar_events_25_75","default_rule",null],"description":"10th-90th of 10+ own runs; min-max of 3-9 own runs; the pooled middle half (25th/75th, ENG-2370: pooled sets only ever show medians and middle halves); or the default rule. Never narrower than +/-max(15% of what is left, 5% of capacity), x1.5 when cold."},"demand_p50_uncapped":{"type":["integer","null"],"description":"Paid tickets the curve projects at the same pace with no capacity ceiling, through the sale window (median): the counterfactual for suggested moves. Unlimited: equals at_this_pace."},"demand_p90_uncapped":{"type":["integer","null"],"description":"High end of the uncapped demand."},"forecast_reason_detail":{"type":["string","null"],"enum":["not_enough_data_yet",null]},"at_this_pace":{"type":"integer","description":"Paid tickets at the close if the 7-day pace holds."},"sell_out_date":{"type":["string","null"],"format":"date","description":"The day it sold out, or the median forecast sell-out day (7-day pace along the path). Null when not forecast to sell out."},"sell_out_from":{"type":["string","null"],"format":"date","description":"Earliest sell-out day (at the high end of the range)."},"sell_out_to":{"type":["string","null"],"format":"date","description":"Latest sell-out day (at the low end); null when the low end does not sell out."},"pace":{"type":"number","description":"Paid tickets per day over the last 7 days (the days available on a small sample)."},"pace_14d":{"type":"number"},"needed_pace":{"type":["number","null"],"description":"Paid tickets per day needed to fill sellable capacity by the close."},"vs_path":{"type":["integer","null"],"description":"Paid tickets ahead (+) or behind (-) the path today."},"status":{"type":["string","null"],"enum":["ahead","on_track","slightly_behind","behind","too_early",null],"description":"on_track within 2% of the path (inclusive); ahead above 1.02; slightly_behind 0.88 to under 0.98; behind under 0.88; too_early in the first 3 days or while under 5% of the window is gone (or before a type opens). Yesterday's status holds until the ratio is past a threshold by 1 point."},"forecast_daily":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastDay"},"description":"Forecast paid tickets per remaining day; sums to likely_finish - sold; zero after the sell-out day."},"pace_short":{"type":"boolean","description":"Pace is from fewer than 7 days of sales (not the Conversion 'small sample')."},"sold_out":{"type":"boolean","description":"Paid tickets reached sellable capacity (the run: or the event/every show is marked sold out)."},"sold_out_at":{"type":["string","null"],"format":"date","description":"First day (event's zone) paid tickets, refunded ones included, reached sellable capacity; null if never."},"reopened_units":{"type":"integer","description":"Sold out once and now below capacity again: capacity minus sold; else 0."},"currency":{"type":["string","null"],"description":"Set only when the run (or type) has exactly one currency; else see gross_by_currency."},"live_price_cents":{"type":["integer","null"],"description":"The type's price after its best automatic discount at its usual order size (no codes, no guest fees). On the run: the price of a ticket at the mix still to sell (each type weighed by its remaining sellable units; by paid mix when a priced type is uncapped), in the run's one currency; null with several."},"gross_so_far_cents":{"type":["integer","null"],"description":"Ticket money so far (Sales rules, net of refunds)."},"likely_finish_gross_cents":{"type":["integer","null"],"description":"Gross at the finish: each type at its live price, summed. Free types count in units only."},"range_low_gross_cents":{"type":["integer","null"],"description":""},"range_high_gross_cents":{"type":["integer","null"],"description":""},"gross_this_week_cents":{"type":["integer","null"],"description":"Gross this week (calendar Monday 00:00 local to now; before 12:00 Monday the last full week), net of refunds, guest fees excluded. One currency only."},"gross_prev_week_cents":{"type":["integer","null"],"description":"The same span last week up to the same local hour (or the full week before)."},"gross_by_currency":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastCurrencyGross"},"description":"Money per currency; never summed across currencies."},"method":{"type":"string","enum":["own_history","similar_events","default_curve"]},"own_weight":{"type":"number","description":"Weight on the organizer's own curve in the path (0..1)."},"model_version":{"type":"string","examples":["path-blend-v3"]},"basis":{"type":"string","description":"e.g. \"Based on your pace and your 4 past events\", \"Based on your pace and 42 similar shows\", \"Based on your last 14 days of sales\". Never names anyone."},"path_gross_cents":{"type":["array","null"],"items":{"type":"integer"},"description":"ENG-2402: the path in sales (cents), index-aligned with path, for a single-currency forecast (run or type): below what has sold, units × gross so far ÷ sold; from there, gross so far plus each ticket still to sell at the live price (the run: the weighted live price, or the money goal's plan). Null with more than one currency or no path."},"band_low_gross_cents":{"type":["array","null"],"items":{"type":"integer"},"description":"ENG-2402: band_low in sales by the same rule. Null when band_low is."},"band_high_gross_cents":{"type":["array","null"],"items":{"type":"integer"},"description":"ENG-2402: band_high in sales by the same rule. Null when band_high is."},"forecast_daily_gross_cents":{"type":["array","null"],"items":{"type":"integer"},"description":"ENG-2402: index-aligned with forecast_daily: likely_finish_gross_cents − gross_so_far_cents spread over the days as the units are, so the forecast ends at the Verdict's likely finish."},"vs_path_gross_cents":{"type":["integer","null"],"description":"ENG-2402: gross_so_far_cents − path_gross_cents on today (the one money gap)."},"compare_from":{"type":["string","null"],"format":"date","description":"ENG-2402: the first day (event's zone) the status can leave too_early. Null without a path."}}},"SalesForecastType":{"type":"object","required":["tier_id","tier_name","tier_scope","show_event_id","sold","forecast","reason","handover_to_tier_id","handover_units","area_id"],"properties":{"tier_id":{"type":"string","format":"uuid"},"tier_name":{"type":"string"},"tier_scope":{"type":"string","enum":["occurrence","pass"]},"show_event_id":{"type":["string","null"],"format":"uuid","description":"Series only: the show a single-show type sells for. Null for a pass and on an event."},"sold":{"type":"integer"},"forecast":{"oneOf":[{"$ref":"#/components/schemas/SalesForecast"},{"type":"null"}]},"reason":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastReason"},{"type":"null"}]},"handover_to_tier_id":{"type":["string","null"],"format":"uuid","description":"The next price step (same show, not hidden, next by sort order, opening at or after this type's sale end) that this type's demand after its close moves to."},"handover_units":{"type":"integer"},"area_id":{"type":["string","null"],"format":"uuid","description":"ENG-2480: set when the type shares an area's seats with other types. Its own forecast then has no seat ceiling (pace only, unlimited); the area's forecast is in the run's pools."}}},"SalesForecastPool":{"type":"object","description":"ENG-2480: one area whose seats two or more types share, forecast as one unit against its sellable seats (counted once).","required":["area_id","tier_ids","forecast","reason"],"properties":{"area_id":{"type":"string","format":"uuid"},"tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Member types, in Setup order."},"forecast":{"oneOf":[{"$ref":"#/components/schemas/SalesForecast"},{"type":"null"}]},"reason":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastReason"},{"type":"null"}]}}},"SalesFirstToSellOut":{"type":"object","description":"ENG-2480: the type (or shared area) that sells out first: the earliest sell-out date among types on sale not sold out, past their cold start, whose likely finish and low range both reach capacity. Ties go to the higher share sold, then Setup order.","required":["tier_id","area_id","sell_out_date"],"properties":{"tier_id":{"type":["string","null"],"format":"uuid","description":"Null when it is a shared area."},"area_id":{"type":["string","null"],"format":"uuid"},"sell_out_date":{"type":"string","format":"date"}}},"SalesForecastTypeRow":{"type":"object","description":"ENG-2480: one ticket type of the event or series, whatever the forecast's state.","required":["tier_id","tier_name","tier_scope","show_event_id","sort_order","is_active","is_hidden","tier_kind","sales_start_at","sales_end_at","capacity","capacity_total","held","comped","sold","gross_so_far_cents","currency","area_id","handover_to_tier_id","handover_units"],"properties":{"tier_id":{"type":"string","format":"uuid"},"tier_name":{"type":"string"},"tier_scope":{"type":"string","enum":["occurrence","pass"]},"show_event_id":{"type":["string","null"],"format":"uuid"},"sort_order":{"type":"integer"},"is_active":{"type":"boolean"},"is_hidden":{"type":"boolean"},"tier_kind":{"type":"string"},"sales_start_at":{"type":["string","null"],"format":"date-time"},"sales_end_at":{"type":["string","null"],"format":"date-time"},"capacity":{"type":["integer","null"],"description":"Sellable seats (total less held and comped); a shared area's, the same on each member. Null when unlimited."},"capacity_total":{"type":["integer","null"]},"held":{"type":"integer"},"comped":{"type":"integer"},"sold":{"type":"integer","description":"Paid units still held (the forecast's sold rule)."},"gross_so_far_cents":{"type":"integer","description":"Sales after refunds, in currency."},"currency":{"type":["string","null"]},"area_id":{"type":["string","null"],"format":"uuid","description":"Set when two or more types share this area's seats."},"handover_to_tier_id":{"type":["string","null"],"format":"uuid"},"handover_units":{"type":"integer"}}},"SalesForecastPeer":{"type":"object","description":"The anonymous pooled set (ENG-2370 rule: 5+ organizers, 20+ runs, none over 25%, last 12 months, the viewer excluded). Counts, criteria and a month span only, never a name.","required":["n_events","n_organizers","span","criteria"],"properties":{"n_events":{"type":"integer"},"n_organizers":{"type":"integer"},"span":{"type":"object","description":"Month range of the pooled runs' last shows (YYYY-MM).","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}},"criteria":{"type":"array","items":{"type":"string"},"description":"The 'Similar means' chips of the finest qualifying cell, e.g. Music, 500-1,999 capacity, US-West, $25-$49 average price."}}},"SalesForecastDrivers":{"type":"object","description":"Traffic vs conversion when behind, from the funnel report. Only with 50%+ of online orders tracked.","properties":{"visitors":{"type":"integer"},"buyers":{"type":"integer"},"conversion":{"type":"number"},"tickets_per_buyer":{"type":"number"},"expected_conversion":{"type":["number","null"],"description":"Median conversion of the organizer's own recent comparable runs; null when none were tracked."},"shortfall_units":{"type":"integer"},"traffic_gap_units":{"type":"integer"},"conversion_gap_units":{"type":["integer","null"]},"close_gap":{"type":"object","properties":{"more_visitors":{"type":"integer"},"conversion_from":{"type":"number"},"conversion_to":{"type":"number"}}}}},"SalesSeriesType":{"type":"object","required":["key","name","kind","tier_ids","sort_order","is_active","sold","comps","free","unlimited"],"properties":{"key":{"type":"string","description":"A ticket/pass type id, or show_tickets (a series' single-show types combined)."},"name":{"type":"string"},"kind":{"type":"string","enum":["type","pass","show_tickets"]},"tier_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"sort_order":{"type":"integer"},"is_active":{"type":"boolean"},"sold":{"type":"integer","description":"Paid units still held (Σ over bins)."},"comps":{"type":"integer","description":"Comps issued and still live (Σ over bins)."},"free":{"type":"boolean","description":"Every type in it is free: no revenue."},"unlimited":{"type":"boolean","description":"No type in it has a capacity limit."}}},"SalesSeriesRow":{"type":"object","required":["key","paid_units","sales_cents","orders","comps_issued"],"properties":{"key":{"type":"string"},"paid_units":{"type":"integer","description":"Paid on a day of this bin (event's zone) and still held; a refund, cancellation or chargeback leaves its paid day."},"sales_cents":{"type":["integer","null"],"description":"Ticket and pass prices paid, net of refunds, order coupons spread across types, guest fees out (the Verdict's sales), by paid day. Null with more than one currency."},"orders":{"type":"integer","description":"Paid orders with a ticket of this key still held."},"comps_issued":{"type":"integer","description":"Comps issued on a day of this bin and still live; never sales."}}},"SalesSeriesBin":{"type":"object","required":["key","last_day","rows"],"properties":{"key":{"type":"string","format":"date","description":"The bin's first day (a week starts Monday in the run's zone)."},"last_day":{"type":"string","format":"date"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/SalesSeriesRow"},"description":"Keys with any activity in the bin."}}},"SalesSeries":{"type":"object","description":"ENG-2402 Sales over time. Σ paid_units = forecast.sold and Σ sales_cents = forecast.gross_so_far_cents.","required":["bin","time_zone","today","start","end","currency","types","bins"],"properties":{"bin":{"type":"string","enum":["day","week"],"description":"day for an event on sale up to 120 days; week for a longer event and every series."},"time_zone":{"type":"string"},"today":{"type":"string","format":"date"},"start":{"type":"string","format":"date","description":"On-sale day, or the first sale if earlier."},"end":{"type":"string","format":"date","description":"The last show's day."},"currency":{"type":["string","null"]},"types":{"type":"array","items":{"$ref":"#/components/schemas/SalesSeriesType"},"description":"Setup order; a series: each pass, then Show tickets."},"bins":{"type":"array","items":{"$ref":"#/components/schemas/SalesSeriesBin"},"description":"Every bin from start to today (or the show day), oldest first."}}},"SalesMarker":{"type":"object","required":["day","kind","label"],"properties":{"day":{"type":"string","format":"date"},"kind":{"type":"string","enum":["on_sale","type_on_sale","code_live","automatic_discount","tracking_link","campaign_landed","postponed","program_live","comps_released"]},"label":{"type":"string","maxLength":24},"move_id":{"type":"string","format":"uuid","description":"ENG-2405 decision 36: the Ways to sell more move this code, landed link or comp release is from; absent otherwise. comps_released markers are only ever from a move."},"landed":{"type":"object","description":"On a campaign_landed marker: the day a tracking link or a named UTM campaign landed (its first day with 25 or more visitors credited to it first, or 10 or more that are at least 25% of the day's visitors). A tracking link that landed has no tracking_link marker. Counts only, over the landed day and the 6 after.","required":["name","channel","visitors","buyers","window_open","coverage_low"],"properties":{"name":{"type":"string","description":"The link's name, or the campaign name, uncut."},"channel":{"type":"string","description":"The channel's label, as Conversion shows it (\"Email\")."},"visitors":{"type":"integer"},"buyers":{"type":"integer","description":"Of those visitors, the ones with a paid order."},"window_open":{"type":"boolean","description":"The 7 days are not over: the counts can still grow."},"coverage_low":{"type":"boolean","description":"Recorded visits cover under half of the online orders."}}}}},"SalesFactsWindow":{"type":"object","required":["from","to","units","cents"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"units":{"type":"integer"},"cents":{"type":["integer","null"]}}},"SalesFactsBest":{"type":["object","null"],"required":["key","units","cents"],"properties":{"key":{"type":"string","format":"date"},"units":{"type":"integer"},"cents":{"type":["integer","null"]}}},"SalesFacts":{"type":"object","required":["last_7","prev_7","best_bin","buyers_peak","orders"],"properties":{"last_7":{"$ref":"#/components/schemas/SalesFactsWindow"},"prev_7":{"$ref":"#/components/schemas/SalesFactsWindow"},"best_bin":{"type":"object","required":["by_units","by_cents"],"properties":{"by_units":{"$ref":"#/components/schemas/SalesFactsBest"},"by_cents":{"$ref":"#/components/schemas/SalesFactsBest"}},"description":"The bin with the most paid units, and with the most sales; the latest on a tie."},"buyers_peak":{"type":["object","null"],"required":["dow","start_hour"],"properties":{"dow":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday."},"start_hour":{"type":"integer","minimum":0,"maximum":22}},"description":"Weekday and 2-hour window with the most paid orders; null under 20 orders."},"orders":{"type":"integer"}}},"OverviewMoveTarget":{"type":"object","description":"ENG-2405 — a ticket type, or a shared area with every type priced on it.","required":["kind","tier_ids"],"properties":{"kind":{"type":"string","enum":["type","area"]},"tier_id":{"type":"string","format":"uuid","description":"Set when kind is type."},"area_id":{"type":"string","format":"uuid","description":"Set when kind is area."},"tier_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"OverviewRiskMove":{"type":"object","description":"ENG-2405 — a behind, on-sale type or area and the idea suggested for it.","required":["target","status","sellable","likely_finish","short_units","pace_14d","needed_pace","currency","live_price_cents","at_risk_cents","sale_end_at","days_left","action","discount"],"properties":{"target":{"$ref":"#/components/schemas/OverviewMoveTarget"},"status":{"type":"string","enum":["slightly_behind","behind"]},"sellable":{"type":"integer"},"likely_finish":{"type":"number"},"short_units":{"type":"integer","description":"Sellable minus likely finish, rounded."},"pace_14d":{"type":"number"},"needed_pace":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true,"description":"Null when the type sells in more than one currency (then no money is shown)."},"live_price_cents":{"type":"integer","nullable":true},"at_risk_cents":{"type":"integer","nullable":true,"description":"Tickets short times the live price."},"sale_end_at":{"type":"string","format":"date-time","nullable":true,"description":"The earliest of the type's sale end and its last show start."},"days_left":{"type":"integer","nullable":true},"action":{"type":"string","enum":["tracking_link","funnel_leak","discount_code"]},"discount":{"type":"object","nullable":true,"description":"Set when action is discount_code: the code's trade-off. No expected effect at launch.","properties":{"percent":{"type":"integer"},"offered_because":{"type":"string","enum":["final_days","no_cause"]},"uses":{"type":"integer"},"tickets_per_order":{"type":"number"},"price_cents":{"type":"integer"},"price_after_cents":{"type":"integer"},"break_even_one_in":{"type":"integer"},"max_tickets":{"type":"integer"},"max_cost_cents":{"type":"integer"}}}}},"OverviewForecastMove":{"type":"object","description":"ENG-2405 — the type or area that sells out first, and the held comps it could release.","required":["target","sell_out_date","sell_out_from","left","pace_14d","comps_held","release","currency"],"properties":{"target":{"$ref":"#/components/schemas/OverviewMoveTarget"},"sell_out_date":{"type":"string","format":"date"},"sell_out_from":{"type":"string","format":"date","nullable":true},"left":{"type":"integer"},"pace_14d":{"type":"number"},"comps_held":{"type":"integer","description":"Comp-held tickets still to give (never partner holds)."},"release":{"type":"object","nullable":true,"properties":{"units":{"type":"integer"},"up_to_cents":{"type":"integer","nullable":true}}},"currency":{"type":"string","nullable":true}}},"OverviewGeographyMove":{"type":"object","description":"ENG-2405 — a city whose share of visitors and of buyers differ by 2x. Aggregates only.","required":["city_key","city","kind","visitor_pct","buyer_pct","band"],"properties":{"city_key":{"type":"string"},"city":{"type":"string"},"kind":{"type":"string","enum":["under","over"]},"visitor_pct":{"type":"integer"},"buyer_pct":{"type":"integer"},"band":{"type":"string","nullable":true,"enum":["near","mid","far",null],"description":"Under 25 km, 25 to 100 km, over 100 km from the venue; null when shows sit in different places or the city has no point."}}},"OverviewMoves":{"type":"object","description":"ENG-2405 — Ways to sell more as facts; the admin words them.","required":["risks","forecast","geography","peer_events","move_states","move_results"],"properties":{"risks":{"type":"array","description":"Every behind, on-sale type or area, largest money at risk first.","items":{"$ref":"#/components/schemas/OverviewRiskMove"}},"forecast":{"allOf":[{"$ref":"#/components/schemas/OverviewForecastMove"}],"nullable":true},"geography":{"allOf":[{"$ref":"#/components/schemas/OverviewGeographyMove"}],"nullable":true},"peer_events":{"type":"integer","nullable":true,"description":"The forecast's qualifying similar events, for the basis line."},"move_states":{"type":"array","description":"Each idea's move record: opened, started (its 7-day window still running) or snoozed (Not now, until it ends or the gap moves more than 25%). A running move wins over a pending one.","items":{"$ref":"#/components/schemas/OverviewMoveState"}},"move_results":{"type":"array","description":"Results of past moves (ENG-2405 B12, B15, B16): up to 20 whole groups of started moves, still measuring included (B1, B5). Groups newest lead first; within a group, moves in Started order.","items":{"$ref":"#/components/schemas/OverviewMoveResult"}}}},"OverviewMoveIdea":{"type":"object","description":"One idea on the panel: the event or series, its kind and its one target (a type or shared area for risk, a type for forecast_comp, a city for opportunity_geo).","required":["kind"],"properties":{"event_id":{"type":"string","format":"uuid"},"production_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["risk","forecast_comp","opportunity_geo"]},"ticket_tier_id":{"type":"string","format":"uuid","nullable":true},"area_id":{"type":"string","format":"uuid","nullable":true},"city_key":{"type":"string","maxLength":200,"nullable":true}}},"OverviewMoveState":{"type":"object","required":["kind","ticket_tier_id","area_id","city_key","move_id","state","started_at","window_end","snoozed_until","linked_coupon_id","linked_hold_id","linked_tracking_link_id","started"],"properties":{"kind":{"type":"string","enum":["risk","forecast_comp","opportunity_geo"]},"ticket_tier_id":{"type":"string","format":"uuid","nullable":true},"area_id":{"type":"string","format":"uuid","nullable":true},"city_key":{"type":"string","nullable":true},"move_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["opened","started","snoozed"]},"started_at":{"type":"string","format":"date-time","nullable":true},"window_end":{"type":"string","format":"date-time","nullable":true},"snoozed_until":{"type":"string","format":"date-time","nullable":true},"linked_coupon_id":{"type":"string","format":"uuid","nullable":true},"linked_hold_id":{"type":"string","format":"uuid","nullable":true},"linked_tracking_link_id":{"type":"string","format":"uuid","nullable":true},"started":{"description":"What a started move is linked to, for its Started line: the code as saved, the comps still held against those held at open, or the tracking link. Null unless started.","nullable":true,"oneOf":[{"type":"object","required":["kind","code","percent_bps","amount_cents","max_redemptions","ends_at","tier_ids"],"properties":{"kind":{"type":"string","enum":["code"]},"code":{"type":"string","nullable":true},"percent_bps":{"type":"integer","nullable":true},"amount_cents":{"type":"integer","nullable":true},"max_redemptions":{"type":"integer","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"tier_ids":{"type":"array","description":"The types the code covers; empty means every type.","items":{"type":"string","format":"uuid"}}}},{"type":"object","required":["kind","held_now","held_at_open"],"properties":{"kind":{"type":"string","enum":["comps"]},"held_now":{"type":"integer"},"held_at_open":{"type":"integer","nullable":true}}},{"type":"object","required":["kind","name","code"],"properties":{"kind":{"type":"string","enum":["tracking_link"]},"name":{"type":"string"},"code":{"type":"string"}}},{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["city_list"]}}}]}}},"OverviewMoveResult":{"type":"object","description":"A started move, listed from Started on, still measuring included (ENG-2405 PR 3b, B1, B5). Measured once at window end + 24h, then frozen; until then status is null (Measuring). Units are tickets; the headline is the whole scope's actual paid units minus what was expected anyway.","required":["kind","ticket_tier_id","area_id","city_key","move_id","started_at","window_end","measured_at","status","reason","note","units","low_units","high_units","type_units","redemptions","discount_cents","currency","traction_orders","traction_tickets","shared_move_ids","group_move_id","city","risk_action","started"],"properties":{"kind":{"type":"string","enum":["risk","forecast_comp","opportunity_geo"]},"ticket_tier_id":{"type":"string","format":"uuid","nullable":true},"area_id":{"type":"string","format":"uuid","nullable":true},"city_key":{"type":"string","nullable":true},"move_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"window_end":{"type":"string","format":"date-time"},"measured_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","nullable":true,"enum":["measured","no_clear_lift","not_measurable",null],"description":"measured: a lift whose range excludes 0; no_clear_lift: the range includes 0; not_measurable: see reason. Null while measuring."},"reason":{"type":"string","nullable":true,"enum":["too_short","no_forecast","no_tracking_link","shifted","price_changed","capacity_changed","sale_dates_changed","show_date_changed","type_turned_off","code_changed","sales_paused","event_cancelled",null],"description":"Why the result is not measurable (decision 28); null otherwise."},"note":{"type":"string","nullable":true,"enum":["covers_more","no_comparison_types",null],"description":"covers_more: the code covers more than the target, so only the whole-scope lift counts; no_comparison_types: no control types, so the target's lift is not adjusted."},"units":{"type":"number","nullable":true,"description":"Whole-scope lift vs expected."},"low_units":{"type":"number","nullable":true},"high_units":{"type":"number","nullable":true},"type_units":{"type":"number","nullable":true,"description":"Of which the target type or area, control-adjusted."},"redemptions":{"type":"integer","nullable":true,"description":"Paid orders that used the linked code in the window and still hold a ticket."},"discount_cents":{"type":"integer","nullable":true,"description":"Discount given by the linked code, in currency; null when not one currency."},"currency":{"type":"string","nullable":true},"traction_orders":{"type":"integer","nullable":true,"description":"Directly the move's own: orders through its code, or through its tracking link as Sources counts them (decision 29). Null for a comp release or city list."},"traction_tickets":{"type":"integer","nullable":true,"description":"Tickets still held on those orders (through the code: its discounted tickets)."},"shared_move_ids":{"type":"array","description":"Other started moves whose windows overlapped this one: the lift is theirs together, named as shared (decision 29).","items":{"type":"string","format":"uuid"}},"group_move_id":{"type":"string","format":"uuid","description":"The group's lead (ENG-2405 A18–A19): the earliest-started move linked to this one by overlap, chains included; this move itself when it overlapped none. The lead's result is the group's lift. Every member of a listed group is listed."},"city":{"type":"string","nullable":true,"description":"A city move's city as Sources names it now (ENG-2405 F5); null for other moves, or when the city no longer appears in Sources."},"risk_action":{"type":"string","nullable":true,"enum":["tracking_link","funnel_leak","discount_code",null],"description":"A Risk move's action, so a move whose code or link was deleted is still named by kind (ENG-2405 G3); null for other kinds."},"started":{"$ref":"#/components/schemas/OverviewMoveState/properties/started"}}},"OverviewMove":{"type":"object","description":"A move record: what was opened with (the prefill a screen opened with ?move={id} fills in) and, once started, what it was linked to.","required":["id","kind","risk_action","event_id","production_id","ticket_tier_id","area_id","city_key","target_tier_ids","suggested_percent_bps","suggested_code","suggested_max_redemptions","suggested_release_qty","hold_qty_at_open","impact_units","impact_cents","impact_label","currency","opened_at","started_at","window_end","linked_coupon_id","linked_hold_id","linked_tracking_link_id","snoozed_until","snoozed_gap"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["risk","forecast_comp","opportunity_geo"]},"risk_action":{"type":"string","enum":["tracking_link","funnel_leak","discount_code"],"nullable":true},"event_id":{"type":"string","format":"uuid","nullable":true},"production_id":{"type":"string","format":"uuid","nullable":true},"ticket_tier_id":{"type":"string","format":"uuid","nullable":true},"area_id":{"type":"string","format":"uuid","nullable":true},"city_key":{"type":"string","nullable":true},"target_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The types the idea is for (a shared area's members)."},"suggested_percent_bps":{"type":"integer","nullable":true},"suggested_code":{"type":"string","maxLength":64,"nullable":true},"suggested_max_redemptions":{"type":"integer","nullable":true},"suggested_release_qty":{"type":"integer","nullable":true},"hold_qty_at_open":{"type":"integer","nullable":true},"impact_units":{"type":"integer"},"impact_cents":{"type":"integer","nullable":true},"impact_label":{"type":"string","enum":["at_risk","up_to"],"nullable":true},"currency":{"type":"string","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"window_end":{"type":"string","format":"date-time","nullable":true},"linked_coupon_id":{"type":"string","format":"uuid","nullable":true},"linked_hold_id":{"type":"string","format":"uuid","nullable":true},"linked_tracking_link_id":{"type":"string","format":"uuid","nullable":true},"snoozed_until":{"type":"string","format":"date-time","nullable":true},"snoozed_gap":{"type":"number","nullable":true}}},"SalesForecastRun":{"allOf":[{"$ref":"#/components/schemas/SalesForecast"},{"type":"object","required":["scope","path_label","goal","goal_reachable","history_count","peer","by_type","pools","first_to_sell_out","drivers","drivers_reason","gross_week_full_weeks","units_this_week","units_prev_week","units_yesterday","close_day","planner"],"properties":{"scope":{"type":"string","enum":["event","series"]},"path_label":{"type":"string","enum":["Path to sell-out","Path to your goal"]},"goal":{"type":["object","null"],"properties":{"tickets":{"type":["integer","null"]},"cents":{"type":["integer","null"]},"currency":{"type":["string","null"],"description":"The currency the money goal was set in. The forecast uses the money goal only while the run sells in this one currency; otherwise it is ignored (goal_reachable null)."}},"description":"The series' sales goal; null when none."},"goal_reachable":{"type":["boolean","null"],"description":"Whether sellable capacity can hold the goal: false → path_label 'Path to sell-out' and the path never climbs past capacity. A tickets goal decides it (true when uncapped), else a money goal in the run's currency. Null when no goal applies."},"history_count":{"type":"integer","description":"Own comparable completed runs in the path."},"peer":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastPeer"},{"type":"null"}]},"by_type":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastType"},"description":"One per ticket/pass type (a pass once). Each type's path is the run's shape scaled to the type; no band; per-type numbers need not sum to the run's."},"pools":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastPool"},"description":"ENG-2480: one forecast per area whose seats two or more types share."},"first_to_sell_out":{"oneOf":[{"$ref":"#/components/schemas/SalesFirstToSellOut"},{"type":"null"}]},"drivers":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastDrivers"},{"type":"null"}]},"drivers_reason":{"type":["string","null"],"enum":["not_behind","low_tracking_coverage","no_funnel",null]},"gross_week_full_weeks":{"type":"boolean","description":"True before 12:00 Monday (event's zone): this/last week are the last full week and the one before."},"units_this_week":{"type":"integer","description":"ENG-2404: paid units still held, by when they were paid, this week (the gross_week_full_weeks rule)."},"units_prev_week":{"type":"integer","description":"ENG-2404: the same for the week before."},"units_yesterday":{"type":"integer","description":"ENG-2404: the same for yesterday, local (the Daily summary email)."},"close_day":{"type":"string","format":"date","description":"ENG-2404: the run's last selling day, local: the latest active type's sale end, else its show, never after the last show."},"planner":{"oneOf":[{"$ref":"#/components/schemas/SalesPlanner"},{"type":"null"}],"description":"ENG-2404: what it takes a day from today to the close; null when hidden."}}}]},"SalesPlanner":{"type":"object","required":["kind","per_day","range_low","range_high","currency","days_left"],"properties":{"kind":{"type":"string","enum":["sell_out","goal_tickets","goal_money"]},"per_day":{"type":"integer","description":"Tickets a day, or minor units a day (whole currency units) for goal_money."},"range_low":{"type":["integer","null"],"description":"This week's lowest daily need from the path's shape (tickets only)."},"range_high":{"type":["integer","null"]},"currency":{"type":["string","null"]},"days_left":{"type":"integer","description":"Local days from today to the close, today included."}}},"EthocaWebhookAck":{"type":"object","required":["received","deferred","decision"],"properties":{"received":{"type":"boolean"},"deferred":{"type":"boolean"},"decision":{"type":"string","enum":["pending","auto_refunded","auto_rejected_with_evidence","flagged_for_review"]}}},"OnSaleNotifyRequestResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["result_code"],"properties":{"result_code":{"type":"string","enum":["on_sale_notify_requested"]}}}}},"PartnerTokenExchangeRequest":{"type":"object","required":["grant_type","subject_token","subject_token_type"],"properties":{"grant_type":{"type":"string","const":"urn:ietf:params:oauth:grant-type:token-exchange"},"subject_token":{"type":"string","description":"The partner's signed user token (JWT)."},"subject_token_type":{"type":"string","enum":["urn:ietf:params:oauth:token-type:jwt","urn:ietf:params:oauth:token-type:access_token"]}}},"PartnerTokenExchangeSession":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["access_token","issued_token_type","token_type","expires_in","refresh_token","axyn_user_id","partner_id","partner_subject","federation_link_id","link_method","created_link"],"properties":{"access_token":{"type":"string","description":"AXYN access token (Supabase JWT) for the buyer."},"issued_token_type":{"type":"string","const":"urn:ietf:params:oauth:token-type:access_token"},"token_type":{"type":"string","const":"bearer"},"expires_in":{"type":"integer"},"refresh_token":{"type":"string"},"axyn_user_id":{"type":"string","format":"uuid"},"partner_id":{"type":"string","description":"Registered partner that vouched for this user."},"partner_subject":{"type":"string","description":"The partner token's `sub`."},"federation_link_id":{"type":"string","format":"uuid"},"link_method":{"type":"string","enum":["email_match","explicit_link"]},"created_link":{"type":"boolean"}}}}},"PartnerTokenExchangeError":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","enum":["invalid_request","unsupported_grant_type","invalid_federation_token","federation_lookup_failed","auth_user_provision_failed","profile_provision_failed","federation_link_failed","privileged_account_requires_direct_sign_in","privilege_check_failed","session_mint_failed"]},"message":{"type":"string","description":"Buyer-facing sentence for `error`; show this, never the code."}}},"ApiError":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"}}},"PaymentFailure":{"type":"object","description":"HF-019 actionable, non-blaming payment-failure copy. Never a bare \"payment failed\": carries a specific reason, a concrete next step, whether the same method can work on retry, and whether the buyer was charged.","required":["failure_reason","recommended_action","retryable","card_charged"],"properties":{"failure_reason":{"type":"string"},"recommended_action":{"type":"string"},"retryable":{"type":"boolean"},"card_charged":{"type":"boolean"}}},"PaymentVerification":{"type":"object","description":"HF-017 synchronous verification result. `status` is definitive (never \"pending forever\"): a live Stripe paymentIntents.retrieve is the truth signal, the webhook is reconciliation backup. `source` is `webhook` when the order was already reconciled in the DB, `stripe_sync` when this call read Stripe live. Issuance is idempotent on payment_intent_id.","required":["status","source","age_seconds"],"properties":{"status":{"type":"string","enum":["paid","failed","pending"]},"source":{"type":"string","enum":["webhook","stripe_sync"]},"payment_intent_id":{"type":"string","nullable":true},"charge_id":{"type":"string","nullable":true},"age_seconds":{"type":"integer","description":"Seconds since the latest payment attempt was recorded; lets the SDK message a calm 'still confirming' state while pending."},"failure":{"allOf":[{"$ref":"#/components/schemas/PaymentFailure"}],"nullable":true,"description":"Present only when status is failed."},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendee"},"description":"ENG-733. The attendees the buyer entered for this order. Empty when the order collected none. Returned only to the buyer who owns the order."}}},"CashAtEntryArrangement":{"type":"object","description":"D6.9 cash-at-entry pre-arrangement. One per cash order: the expected amount the door collects, the auto-cancel grace deadline (event start + grace minutes), and a lifecycle status (pending → collected/cancelled/expired). Door collection is M22c.","required":["id","tenant_id","order_id","venue_event_id","expected_amount_cents","currency","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"expected_amount_cents":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","collected","cancelled","expired"]},"buyer_email":{"type":"string","nullable":true},"grace_expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EventStatus":{"type":"string","enum":["draft","on_sale","paused","sold_out","completed","cancelled"]},"SalesPausedReason":{"type":["string","null"],"enum":["payout_not_ready",null],"description":"Why a listing reads `status: paused` although its organizer left it on sale. `payout_not_ready`: the organizer's payment setup cannot take charges right now, so no checkout can start on any payment method, pay at the door (`cash_at_entry`) included (ENG-2255: AXYN's fee on door cash is taken from the organizer's Stripe balance); show that ticket sales are paused and offer no Continue. Seat hold, preview-total and order create answer 409 `payout_not_ready`. Null otherwise, including when the organizer paused sales itself."},"RefundPolicy":{"type":"string","enum":["none","window","always","producer_discretion"]},"TicketingLayoutMode":{"type":"string","enum":["general","section_and_type","reserved_seat"],"description":"general is GA / standing-room: no seating chart and no seating_ready publish gate (hard floor). section_and_type and reserved_seat require POST /v1/events/{eventId}/seating:ready before publish."},"EventInput":{"type":"object","properties":{"title":{"type":"string","minLength":1},"starts_at":{"type":"string","format":"date-time"},"doors_open":{"type":"string","format":"date-time","nullable":true,"description":"ENG-3339. When the door starts admitting. A scan before it is refused `not_yet_valid` with this time; a pass's own entry time (`admit_times` on the tier) wins for its holders. Null opens the door at `starts_at`. Must not be after the event's end (sent or stored): 400 `doors_open_after_end`."},"ends_at":{"type":"string","format":"date-time","nullable":true},"sales_start_at":{"type":"string","format":"date-time","nullable":true},"sales_end_at":{"type":"string","format":"date-time","nullable":true},"venue_id":{"type":"string","format":"uuid","nullable":true},"ticketing_layout_mode":{"$ref":"#/components/schemas/TicketingLayoutMode"},"refunds_enabled":{"type":"boolean"},"refund_policy":{"$ref":"#/components/schemas/RefundPolicy"},"refund_window_hours":{"type":"integer","minimum":0,"nullable":true},"low_inventory_velocity_threshold":{"type":"integer","minimum":1,"nullable":true,"description":"HF-003: per-event sales-per-hour bar for the truthful low-inventory flag (default 5/hr when null). Organizers may lower it; the 20% inventory ceiling is fixed and cannot be raised."},"capacity":{"type":"integer","minimum":0,"nullable":true,"description":"ENG-142: optional occurrence fire-code / room capacity. Null leaves the ceiling off. When set, allocation writes that would commit more sellable units than this number are refused with capacity_ceiling_blocked."},"organizer_message":{"type":"string","nullable":true,"maxLength":500,"description":"Optional plain-text message to ticket holders (D7.8). Shown on confirmation, Live Pass, and purchase email. Not an entry/QR code."},"house_rules":{"type":"string","nullable":true,"maxLength":8000,"description":"ENG-1664 optional plain-text House rules for this listing (series or independent event), not the venue. Child series dates reject writes. Empty or null hides the buyer section."},"waitlist_join_mode":{"type":"string","enum":["off","sold_out","always"],"description":"ENG-1598 waitlist join opt-in for this listing. off keeps sold out an honest dead end with no button; sold_out opens the waitlist once nothing is sellable; always opens it from the moment the listing is live. Omit to leave the stored mode alone. Defaults to off on create."},"venue_fee_cents":{"type":"integer","minimum":0,"description":"ENG-1724 named venue fee charged on every paid ticket, in cents. 0 means none. Set it with PATCH once the event has ticket types: create refuses a fee above 0, because the cap is measured against the cheapest paid ticket. Send venue_fee_cents whenever you send the label or the reason. At most 15% of the event's cheapest paid ticket, and it may not rise once a ticket has sold. Free tickets and comps never carry it. Send 0 to clear the fee, which clears the label and reason too."},"venue_fee_label":{"type":["string","null"],"enum":["restoration","preservation","facility","venue_improvement",null],"description":"Which kind of venue fee this is. AXYN writes the wording guests see, so a fee can never read like a service or processing charge. Required when venue_fee_cents is above 0."},"venue_fee_reason":{"type":["string","null"],"maxLength":80,"description":"One plain line telling guests what the fee pays for, shown under it at checkout (for example \"Restores this 1937 theatre\"). Required when venue_fee_cents is above 0."},"who_it_is_for":{"type":"string","nullable":true,"maxLength":280,"description":"ENG-1663 listing copy. Freeform Who it is for line. Independent events store the listing line here. Child shows store an optional override; empty or null inherits the series line. Not a door check. Do not fail checkout on this string."},"address_collection_mode":{"type":"string","enum":["postal_only","full"],"description":"Checkout address collection. Postal and country remain required in both modes."},"phone_collection_mode":{"type":"string","enum":["off","optional","required"],"description":"Checkout purchaser phone collection."},"attendee_details_mode":{"type":["string","null"],"enum":["off","required",null],"description":"ENG-733. Require a name for every ticket. `required`: checkout must send a first name and last name for each ticket (see `attendees` on POST /v1/orders). An email per ticket is optional: with one, that person also gets their pass by email. `off`: checkout collects the purchaser only. Null on a show in a series follows the series setting. Null on an independent event means off. Default off."},"minimum_age":{"type":["integer","null"],"enum":[0,18,21,null],"description":"ENG-2300. Minimum age: 0 (all ages), 18 or 21. Null clears the event's own value: a program in a series then follows the series, and an independent event is all ages. Raising it after tickets are sold is allowed and ticket holders are not notified; tell them yourself."},"cash_at_entry_enabled":{"type":"boolean","description":"ENG-1603: when true, buyers may choose pay at the door (cash). Default false."},"texting_enabled":{"type":"boolean","description":"ENG-2871: the event's Texting switch. Default false; set it with PATCH (create ignores it, and a copied event starts off). Checkout offers the text boxes only when this is true and phone_collection_mode is not off."},"partner_embed_analytics_enabled":{"type":"boolean","description":"ENG-2175: Analytics on partner embeds. When true, the Web SDK and the hosted shop post first-party funnel steps (view, tier_select, checkout_start) to POST /v1/events/{eventId}/views. Default false: nothing is sent or stored, and that route refuses funnel facts for the event (422 embed_analytics_disabled). The browser Global Privacy Control signal always opts the buyer out."},"entry_fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"Entry & check-in default: how guests of this show get in when a ticket type follows the event. digital = Live Pass only; will_call / badge = a pickup desk. Set with PATCH /v1/events/{eventId} (create ignores entry_*). Validated by the ticket-type badge pickup rules (a desk needs entry_pickup_location_label and hours). Every ticket type with pickup_follows_event gets a copy in the same transaction; turning the desk off is refused (409 badge_pickup_locked_by_sales) while a following type has live badge tickets."},"entry_pickup_requires_scan":{"type":"boolean","description":"Entry default, as ticket-type pickup_requires_scan. False: the badge handoff checks the guest in."},"entry_pickup_required_before_admit":{"type":"boolean","description":"Entry default: guests must pick up before the door admits (desk only)."},"entry_pickup_id_check_required":{"type":"boolean","description":"Entry default: the desk checks photo ID (desk only)."},"entry_pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"Entry default: where the desk is, e.g. Box office (desk only)."},"entry_pickup_address":{"type":["string","null"],"maxLength":300,"description":"Entry default: desk street address when it is not at the event address."},"entry_pickup_instructions":{"type":["string","null"],"maxLength":1000,"description":"Entry default: a note guests see about the desk."},"entry_pickup_opens_at":{"type":["string","null"],"format":"date-time","description":"Entry default: desk opens (required with a desk)."},"entry_pickup_closes_at":{"type":["string","null"],"format":"date-time","description":"Entry default: desk closes (required with a desk)."},"entry_pickup_reminder_enabled":{"type":"boolean","description":"Entry default: day-before pickup reminder email."},"entry_re_entry_policy":{"type":["string","null"],"enum":["no_reentry","n_times","unlimited",null],"description":"Entry default re-entry for ticket types with re_entry_follows_event. Null: the standing rule (no_reentry on a standalone show, unlimited on a series show). The door still reads each ticket type's own re_entry_policy (ENG-1920)."},"entry_re_entry_limit":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Total entries (first included) when entry_re_entry_policy is n_times; null otherwise."},"cash_at_entry_grace_minutes":{"type":"integer","minimum":1,"description":"Minutes after event start before unpaid cash holds expire. Default 60."},"cash_at_entry_max_inventory_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Max share of event inventory that may be held for unpaid cash checkout. Default 20."},"partner_commerce_pixel_enabled":{"type":"boolean","description":"ENG-623 / ENG-635: when true, commerce-pixel view ingest may write headless_api event_view_fact rows (no browser API key required). Default false."},"cover_crops":{"$ref":"#/components/schemas/CoverCrops"},"hero_image_url":{"type":"string","nullable":true,"description":"https cover URL, site-relative path, or null to clear"},"accessible_release_rule":{"type":"string","enum":["never","when_section_sold","when_price_sold","when_house_sold"],"description":"ENG-1131 organizer rule for when accessible inventory may release (default never)."},"seat_select_default":{"type":"string","enum":["find_n","pick_seat"],"description":"ENG-1131 default buyer seat-select mode for reserved charts (default find_n)."},"stage_end":{"type":"string","enum":["north","east","south","west"],"nullable":true,"description":"ENG-1674 side of the seat chart the stage is on (north = top, small pos_y). Null = not declared; the maps infer it."},"getting_in_parking":{"type":["string","null"],"maxLength":200,"description":"Where to park, in one line. Null or blank hides the line on the buyer page."},"getting_in_access":{"type":["string","null"],"maxLength":200,"description":"How to get in when getting in is not obvious (which door, step-free route, ID rules). Null or blank hides the line."},"getting_in_arrival":{"type":["string","null"],"maxLength":200,"description":"When to turn up, in one line. Null or blank hides the line."},"walk_up_sales_enabled":{"type":"boolean","default":false,"description":"ENG-246 Sell at the door: staff walk-up sales via scanner when true."}}},"Event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"previous_event_id":{"type":["string","null"],"format":"uuid","description":"ENG-2417. The earlier event this one follows (its previous edition), set in Setup; null when none. Organizer reads only: never on buyer event detail, discovery, outbox or partner payloads."},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"organizer_message":{"type":"string","nullable":true,"maxLength":500,"description":"Optional plain-text message to ticket holders (D7.8)."},"house_rules":{"type":"string","nullable":true,"maxLength":8000,"description":"ENG-1664 optional plain-text House rules for this independent listing. Null on series child dates; edit the production parent. Buyer EventDetail returns the series copy for those dates."},"waitlist_join_mode":{"type":"string","enum":["off","sold_out","always"],"description":"ENG-1598 waitlist join opt-in for this listing. off, sold_out, or always. Always present; off until an organizer opts in."},"venue_fee_cents":{"type":"integer","minimum":0,"description":"ENG-1724 named venue fee charged on every paid ticket, in cents. 0 means none. Set it with PATCH once the event has ticket types: create refuses a fee above 0, because the cap is measured against the cheapest paid ticket. Send venue_fee_cents whenever you send the label or the reason. At most 15% of the event's cheapest paid ticket, and it may not rise once a ticket has sold. Free tickets and comps never carry it. Send 0 to clear the fee, which clears the label and reason too."},"venue_fee_label":{"type":["string","null"],"enum":["restoration","preservation","facility","venue_improvement",null],"description":"Which kind of venue fee this is. AXYN writes the wording guests see, so a fee can never read like a service or processing charge. Required when venue_fee_cents is above 0."},"venue_fee_reason":{"type":["string","null"],"maxLength":80,"description":"One plain line telling guests what the fee pays for, shown under it at checkout (for example \"Restores this 1937 theatre\"). Required when venue_fee_cents is above 0."},"who_it_is_for":{"type":"string","nullable":true,"maxLength":280,"description":"ENG-1663 listing copy. Independent events: the listing line. Child shows: optional override (null inherits the series line). Not a door check."},"status":{"$ref":"#/components/schemas/EventStatus"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"sales_start_at":{"type":"string","format":"date-time","nullable":true},"sales_end_at":{"type":"string","format":"date-time","nullable":true},"ticketing_layout_mode":{"$ref":"#/components/schemas/TicketingLayoutMode"},"refunds_enabled":{"type":"boolean"},"refund_policy":{"$ref":"#/components/schemas/RefundPolicy"},"refund_window_hours":{"type":"integer","nullable":true},"refund_policy_summary":{"type":"string"},"low_inventory_velocity_threshold":{"type":"integer","nullable":true},"capacity":{"type":"integer","minimum":0,"nullable":true,"description":"ENG-142 optional occurrence room capacity. Null means the ceiling is off."},"address_collection_mode":{"type":"string","enum":["postal_only","full"]},"phone_collection_mode":{"type":"string","enum":["off","optional","required"]},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. Effective setting for this event: the show's own value, else the series value, else `off`. When `required`, checkout must send a first and last name for every ticket. An email per ticket is optional."},"attendee_details_mode_override":{"type":["string","null"],"enum":["off","required",null],"description":"ENG-733. This show's own value when it belongs to a series and differs from following it. Null when the show follows the series setting. Always null for an independent event."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. Minimum age shown to guests and door staff: 0 (all ages), 18 or 21. Effective value: the event's own, else its series'. When it is 18 or 21, show guests the age and that they need photo ID. AXYN never checks an age and never blocks a purchase on it."},"minimum_age_override":{"type":["integer","null"],"enum":[0,18,21,null],"description":"ENG-2300. This program's own minimum age when it belongs to a series and has one. Null when it follows the series. Always null for an independent event."},"cash_at_entry_enabled":{"type":"boolean","description":"ENG-1603: organizer pay-at-door (cash) toggle. Default false."},"texting_enabled":{"type":"boolean","description":"ENG-2871: the event's Texting switch. Default false. Checkout offers the text boxes only when this is true and phone_collection_mode is not off."},"partner_embed_analytics_enabled":{"type":"boolean","description":"ENG-2175: Analytics on partner embeds. When true, the Web SDK and the hosted shop post first-party funnel steps (view, tier_select, checkout_start) to POST /v1/events/{eventId}/views. Default false: nothing is sent or stored, and that route refuses funnel facts for the event (422 embed_analytics_disabled). The browser Global Privacy Control signal always opts the buyer out."},"entry_fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"Entry & check-in default: how guests of this show get in when a ticket type follows the event. digital = Live Pass only; will_call / badge = a pickup desk. Set with PATCH /v1/events/{eventId} (create ignores entry_*). Validated by the ticket-type badge pickup rules (a desk needs entry_pickup_location_label and hours). Every ticket type with pickup_follows_event gets a copy in the same transaction; turning the desk off is refused (409 badge_pickup_locked_by_sales) while a following type has live badge tickets."},"entry_pickup_requires_scan":{"type":"boolean","description":"Entry default, as ticket-type pickup_requires_scan. False: the badge handoff checks the guest in."},"entry_pickup_required_before_admit":{"type":"boolean","description":"Entry default: guests must pick up before the door admits (desk only)."},"entry_pickup_id_check_required":{"type":"boolean","description":"Entry default: the desk checks photo ID (desk only)."},"entry_pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"Entry default: where the desk is, e.g. Box office (desk only)."},"entry_pickup_address":{"type":["string","null"],"maxLength":300,"description":"Entry default: desk street address when it is not at the event address."},"entry_pickup_instructions":{"type":["string","null"],"maxLength":1000,"description":"Entry default: a note guests see about the desk."},"entry_pickup_opens_at":{"type":["string","null"],"format":"date-time","description":"Entry default: desk opens (required with a desk)."},"entry_pickup_closes_at":{"type":["string","null"],"format":"date-time","description":"Entry default: desk closes (required with a desk)."},"entry_pickup_reminder_enabled":{"type":"boolean","description":"Entry default: day-before pickup reminder email."},"entry_re_entry_policy":{"type":["string","null"],"enum":["no_reentry","n_times","unlimited",null],"description":"Entry default re-entry for ticket types with re_entry_follows_event. Null: the standing rule (no_reentry on a standalone show, unlimited on a series show). The door still reads each ticket type's own re_entry_policy (ENG-1920)."},"entry_re_entry_limit":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Total entries (first included) when entry_re_entry_policy is n_times; null otherwise."},"cash_at_entry_grace_minutes":{"type":"integer","minimum":1,"description":"Minutes after event start before unpaid cash holds expire. Default 60."},"cash_at_entry_max_inventory_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Max share of event inventory that may be held for unpaid cash checkout. Default 20."},"partner_commerce_pixel_enabled":{"type":"boolean","description":"ENG-623 / ENG-635: when true, commerce-pixel view ingest may write headless_api event_view_fact rows (no browser API key required). Default false."},"accessible_release_rule":{"type":"string","enum":["never","when_section_sold","when_price_sold","when_house_sold"],"description":"ENG-1131 organizer rule for when accessible inventory may release (default never)."},"seat_select_default":{"type":"string","enum":["find_n","pick_seat"],"description":"ENG-1131 default buyer seat-select mode for reserved charts (default find_n)."},"stage_end":{"type":"string","enum":["north","east","south","west"],"nullable":true,"description":"ENG-1674 side of the seat chart the stage is on (north = top, small pos_y). Null = not declared; the maps infer it."},"walk_up_sales_enabled":{"type":"boolean","default":false,"description":"ENG-246 Sell at the door: staff walk-up sales via scanner when true."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"getting_in_parking":{"type":["string","null"],"maxLength":200,"description":"Where to park, in one line. Null or blank hides the line on the buyer page."},"getting_in_access":{"type":["string","null"],"maxLength":200,"description":"How to get in when getting in is not obvious (which door, step-free route, ID rules). Null or blank hides the line."},"getting_in_arrival":{"type":["string","null"],"maxLength":200,"description":"When to turn up, in one line. Null or blank hides the line."},"guest_visibility":{"type":"string","enum":["everyone","passes","no_one"],"description":"ENG-2344. Organizer reads. Who can see this program of a series: `everyone` follows the series' two lineup switches, `passes` shows it only to holders of the pass types in `guest_visibility_passes`, `no_one` never shows it to guests. It narrows what the series switches allow and never widens it. It never changes who is admitted, what a pass opens, who can claim or what is on sale. Always `everyone` on an event outside a series."},"guest_visibility_passes":{"type":"array","description":"ENG-2344. Organizer reads. The pass types chosen for `passes`. Empty for any other setting.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"guest_visibility_eligible_passes":{"type":"array","description":"ENG-2344. Organizer reads. Every pass type of the series that opens this program: the only ones that can be chosen.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"guest_visibility_unlisted_passes":{"type":"array","description":"ENG-2344. Organizer reads. With `passes`: the pass types that open this program and are not chosen. Their holders get in and do not see it listed. Empty for any other setting.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"EventVenueFacts":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Native venue id when linked; null for fallback name-only facts."},"name":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"address_line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true,"description":"State / province for directions and wallet face."},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"distance_band_available":{"type":"boolean","description":"False when the venue has no geo point, so purchaser distance-band capture remains unavailable."}}},"EventPriceSummary":{"type":"object","required":["low_cents","high_cents","currency","has_listed_price"],"properties":{"low_cents":{"type":"integer","description":"All-in minimum across active tiers (HF-001)."},"high_cents":{"type":"integer","description":"All-in maximum across active tiers (HF-001)."},"currency":{"type":"string"},"has_listed_price":{"type":"boolean","description":"True when low_cents/high_cents are listed all-in prices. False means no tier is priced yet (show \"See pricing\"). True with low_cents 0 means the cheapest buyable tier is free (show \"Free\")."}}},"HeldTicketSeries":{"type":"object","description":"ENG-2337. The series a held ticket's program belongs to.","required":["title","lineup_on_live_pass"],"properties":{"title":{"type":"string"},"lineup_on_live_pass":{"type":"boolean","description":"Whether ticket holders see the series' programs. False: name no program."}}},"HeldTicketPass":{"type":"object","description":"ENG-2338. What a pass's holder is told beside its name. Every value comes from the programs the pass admits that are not cancelled, never from the program the ticket row sits on.","required":["valid_from","valid_to","place","minimum_age"],"properties":{"valid_from":{"type":["string","null"],"format":"date-time","description":"Start of the first program the pass admits that is not cancelled."},"valid_to":{"type":["string","null"],"format":"date-time","description":"Start of the last program the pass admits that is not cancelled."},"place":{"type":["string","null"],"description":"The one place every program the pass admits shares. Null when they are in different places, or when it admits none."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"The highest minimum age among the programs the pass admits: 0 (all ages), 18 or 21. 0 when it admits none."}}},"EventDetail":{"type":"object","required":["id","event_id","title","starts_at","venue","status","ticketing_layout_mode","refund_policy","refund_window_hours","refund_policy_summary","price_summary","low_inventory_truthful","wallet_pay_supported","cover_crops"],"properties":{"id":{"type":"string","format":"uuid","description":"Buyer-flow id (source_venue_event_id; matches /tiers and /add-ons)."},"event_id":{"type":"string","format":"uuid","description":"AXYN-owned event.id (matches /seat-map)."},"title":{"type":"string"},"description":{"type":"string","nullable":true},"hero_image_url":{"type":"string","nullable":true},"organizer_message":{"type":"string","nullable":true,"maxLength":500,"description":"Optional plain-text organizer message shown on this event's page (D7.8). Not an entry/QR code. A ticket holder is shown ticket_holder_note."},"ticket_holder_note":{"type":"string","nullable":true,"maxLength":500,"description":"ENG-2337: the organizer note a ticket holder of this event is shown (confirmation page). A program in a series carries the series note, never its own; a standalone event its own. Null: none."},"house_rules":{"type":"string","nullable":true,"maxLength":8000,"description":"ENG-1664 optional plain-text House rules for this listing. Series dates return the production copy. Hide the section when null or empty. Render as text, never HTML."},"who_it_is_for":{"type":"string","nullable":true,"maxLength":280,"description":"ENG-1663. Effective Who it is for line for this show (override, else series line, else independent line). Hide when empty. Not a door check. Do not fail checkout on this string."},"venue_fee_cents":{"type":"integer","minimum":0,"description":"ENG-1724 named venue fee charged on every paid ticket, in cents. 0 means none. Set it with PATCH once the event has ticket types: create refuses a fee above 0, because the cap is measured against the cheapest paid ticket. Send venue_fee_cents whenever you send the label or the reason. At most 15% of the event's cheapest paid ticket, and it may not rise once a ticket has sold. Free tickets and comps never carry it. Send 0 to clear the fee, which clears the label and reason too."},"venue_fee_label":{"type":["string","null"],"enum":["restoration","preservation","facility","venue_improvement",null],"description":"Which kind of venue fee this is. AXYN writes the wording guests see, so a fee can never read like a service or processing charge. Required when venue_fee_cents is above 0."},"venue_fee_reason":{"type":["string","null"],"maxLength":80,"description":"One plain line telling guests what the fee pays for, shown under it at checkout (for example \"Restores this 1937 theatre\"). Required when venue_fee_cents is above 0."},"who_it_is_for_override":{"type":"string","nullable":true,"maxLength":280,"description":"ENG-1663. Set only when this child show differs from the series line. Null or omitted means inherit. Independent events always omit this."},"program_note":{"type":["string","null"],"maxLength":160,"description":"A series show's one-line program note. Null on a standalone show. For a series show, description, getting_in_* and (when the show has no image of its own) hero_image_url are the series' values: the series owns the listing."},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"doors_open":{"type":"string","format":"date-time","nullable":true,"description":"Guest doors clock when set and earlier than start. Duration is never stored; clients derive length from starts_at and ends_at."},"timezone":{"type":"string","nullable":true},"venue":{"$ref":"#/components/schemas/EventVenueFacts"},"primary_venue_id":{"type":"string","format":"uuid","nullable":true,"description":"Primary place for directions / wallet location. Equals venue.id today; multi-venue events will keep this as the main pin."},"venues":{"type":"array","items":{"$ref":"#/components/schemas/EventVenueFacts"},"description":"Place list with primary first. Length 0–1 today; multi-venue will append siblings without changing the primary CTA contract."},"status":{"$ref":"#/components/schemas/EventStatus"},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"},"ticketing_layout_mode":{"$ref":"#/components/schemas/TicketingLayoutMode"},"refund_policy":{"$ref":"#/components/schemas/RefundPolicy"},"refund_window_hours":{"type":"integer"},"refund_policy_summary":{"type":"string"},"price_summary":{"$ref":"#/components/schemas/EventPriceSummary"},"low_inventory_truthful":{"type":"boolean"},"wallet_pay_supported":{"type":"boolean"},"wallets":{"$ref":"#/components/schemas/CheckoutWallets"},"custom_questions":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/EventCustomQuestion"}},"address_collection_mode":{"type":"string","enum":["postal_only","full"],"description":"Checkout address collection for this event."},"phone_collection_mode":{"type":"string","enum":["off","optional","required"],"description":"Checkout purchaser phone collection for this event."},"sms_consent":{"type":["object","null"],"description":"ENG-2871: the two unticked text boxes checkout shows under the phone field, in these exact words, then notice_label once under both boxes followed by a `Terms` link to terms_url and a `Privacy` link to privacy_url (ENG-3042). Null when the phone field is off, the event's texting_enabled is off, or the organizer has no display name. Send the ticked ones back as POST /v1/orders sms_consent with this wording_version.","required":["wording_version","event_updates_label","marketing_label","notice_label","terms_url","privacy_url"],"properties":{"wording_version":{"type":"string"},"event_updates_label":{"type":"string"},"marketing_label":{"type":"string"},"notice_label":{"type":"string","description":"Shown once under both boxes, before the Terms and Privacy links."},"terms_url":{"type":"string","format":"uri","description":"AXYN's texting terms. Link text: Terms."},"privacy_url":{"type":"string","format":"uri","description":"AXYN's texting privacy section. Link text: Privacy."}},"additionalProperties":false},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. Effective setting for this event: the show's own value, else the series value, else `off`. When `required`, send one `attendees` entry (first name, last name, optional email) for every ticket on POST /v1/orders, and show the buyer the notice in that route's description."},"attendee_details_mode_override":{"type":["string","null"],"enum":["off","required",null],"description":"ENG-733. This show's own value when it belongs to a series and differs from following it. Null when the show follows the series setting. Always null for an independent event."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. Minimum age shown to guests and door staff: 0 (all ages), 18 or 21. Effective value: the event's own, else its series'. When it is 18 or 21, show guests the age and that they need photo ID. AXYN never checks an age and never blocks a purchase on it."},"minimum_age_override":{"type":["integer","null"],"enum":[0,18,21,null],"description":"ENG-2300. This program's own minimum age when it belongs to a series and has one. Null when it follows the series. Always null for an independent event."},"series_attendee_details_mode":{"type":["string","null"],"enum":["off","required",null],"description":"ENG-733. The series setting when this show belongs to a series. It governs the series' pass types, whatever this show's own value is. Null for an independent event."},"series_lineup":{"type":["object","null"],"description":"ENG-2337. The lineup switches of the series this program belongs to. Null for an independent event. Sent whether or not this read hides the program. When `on_series_page` is false, a guest read of this program carries nothing of its own: `title` is the series title, `description` and `hero_image_url` are the series', `organizer_message` is the series' (or null), `program_note` and `who_it_is_for_override` are null, `lineup` and `tags` are empty and `cover_crops` are the defaults. Day, time, venue, age, status, category and ticket types are unchanged. A key that can write the catalog, reading its own event, always receives the program in full.","required":["on_series_page","on_live_pass"],"properties":{"on_series_page":{"type":"boolean","description":"Guests who do not hold a ticket yet see the series' programs (series page, checkout, search listings)."},"on_live_pass":{"type":"boolean","description":"Guests who hold a pass or ticket see the programs it opens (live pass, My Tickets, wallet pass, ticket emails)."}}},"program_named":{"type":"boolean","description":"ENG-2344. False when this read names the series in place of the program: the series hides its lineup before purchase, or the program is shown only to holders of chosen pass types or to no one. `title` is then the series title and nothing of the program's own is sent, exactly as described under `series_lineup`. Send the guest to the series page. Always true for an independent event."},"cash_at_entry_enabled":{"type":"boolean","description":"ENG-1603: when true, buyer checkout may offer pay at the door (cash). Default false. Grace and inventory cap stay staff-only."},"partner_embed_analytics_enabled":{"type":"boolean","description":"ENG-2175: Analytics on partner embeds. When true, the Web SDK and the hosted shop post first-party funnel steps (view, tier_select, checkout_start) to POST /v1/events/{eventId}/views. Default false: nothing is sent or stored, and that route refuses funnel facts for the event (422 embed_analytics_disabled). The browser Global Privacy Control signal always opts the buyer out."},"tax_not_applicable":{"type":"boolean","description":"Effective tax position: true when no sales tax is added at checkout for this event, so buyer surfaces must not say \"plus tax\". False when tax may be itemized at checkout. Same field as the discovery card."},"has_active_coupons":{"type":"boolean","description":"True when the event has at least one active coupon. Does not expose codes."},"organizer_slug":{"type":"string","nullable":true,"description":"Public organizer slug for hosted shop deep links (/:orgSlug/:eventId)."},"cover_crops":{"$ref":"#/components/schemas/CoverCrops"},"accessible_release_rule":{"type":"string","enum":["never","when_section_sold","when_price_sold","when_house_sold"],"description":"ENG-1131 organizer rule for when accessible inventory may release (default never). Buyer GET includes this so clients do not guess."},"seat_select_default":{"type":"string","enum":["find_n","pick_seat"],"description":"ENG-1131 default buyer seat-select mode for reserved charts (default find_n). Find N is the primary CTA when find_n."},"getting_in_parking":{"type":["string","null"],"maxLength":200,"description":"Where to park, in one line. Null or blank hides the line on the buyer page."},"getting_in_access":{"type":["string","null"],"maxLength":200,"description":"How to get in when getting in is not obvious (which door, step-free route, ID rules). Null or blank hides the line."},"getting_in_arrival":{"type":["string","null"],"maxLength":200,"description":"When to turn up, in one line. Null or blank hides the line."}}},"EventCustomQuestion":{"type":"object","required":["id","prompt","answer_kind","is_required","grain","sort_order","options"],"properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string","maxLength":500},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","acknowledgment"]},"is_required":{"type":"boolean"},"grain":{"type":"string","enum":["per_order","per_ticket"]},"sort_order":{"type":"integer","minimum":0},"options":{"type":"array","items":{"type":"object","required":["id","label","value","sort_order"],"properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":120},"sort_order":{"type":"integer","minimum":0}}}},"show_ids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"ENG-3338: the series programs (event ids) the question is limited to. Null asks every buyer."},"ticket_tier_ids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"ENG-3338, event catalog only: the ticket types (day tickets and passes) that get the guest into a show the question is limited to. Null asks every ticket. Ask a `per_ticket` question only for cart tickets of these types and a `per_order` question only when the cart holds one; order create refuses an answer to a question the cart is not asked with `custom_answer_not_applicable`."}}},"TicketOrderStatus":{"type":"string","enum":["reserved","pending_payment","processing","paid","cancelled","failed","expired","awaiting_cash","partially_refunded","refunded"]},"PaymentMethod":{"type":"string","enum":["card","apple_pay","google_pay","cash_at_entry","ach"]},"TicketOrder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"event_id":{"type":["string","null"],"format":"uuid"},"production_id":{"type":["string","null"],"format":"uuid","description":"The series this order was sold under, fixed at purchase. Null for an event outside a series."},"qty":{"type":"integer"},"purchaser_user_id":{"type":["string","null"],"format":"uuid"},"idempotency_key":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/TicketOrderStatus"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"payment_provider":{"type":["string","null"]},"currency":{"type":"string"},"subtotal_cents":{"type":"integer"},"discount_cents":{"type":"integer","description":"Coupon discount in cents (0 when no coupon). subtotal_cents keeps face-value semantics."},"fees_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"platform_fee_cents":{"type":"integer","description":"AXYN's take on this order: the AXYN fee plus the add-on fee (addon_fee_cents)."},"charged_platform_fee_cents":{"type":"integer","description":"The part of platform_fee_cents guests paid on top."},"addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The add-on fee on this order, inside platform_fee_cents. Fixed at purchase."},"charged_addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The part of addon_fee_cents guests paid (inside charged_platform_fee_cents)."},"addon_fee_name":{"type":["string","null"],"maxLength":32,"description":"ENG-3310. The add-on fee's guest name, snapshotted at purchase."},"addon_fee_description":{"type":["string","null"],"description":"ENG-3310. The add-on fee's public description, snapshotted at purchase. Non-null: the receipt shows the add-on fee as its own line."},"stripe_payment_intent_id":{"type":["string","null"]},"stripe_client_secret":{"type":["string","null"]},"stripe_charge_id":{"type":["string","null"]},"paid_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"cancellation_reason":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time"},"reservation_expires_at":{"type":["string","null"],"format":"date-time"},"hold_extension_count":{"type":"integer","minimum":0,"maximum":10,"description":"Count of explicit buyer hold extensions. Cap is 10 extensions of the current hold window."},"purchaser_email":{"type":["string","null"]},"purchaser_name":{"type":["string","null"]},"purchaser_phone":{"type":["string","null"]},"seat_hold_owner":{"type":["string","null"],"format":"uuid"},"metadata":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"OrderLineInput":{"type":"object","required":["item_type","quantity"],"properties":{"item_type":{"type":"string","enum":["ticket","add_on"]},"ticket_tier_id":{"type":["string","null"],"format":"uuid","description":"Required when item_type=ticket. May be a pass or an occurrence SKU from another night of the same production as venue_event_id."},"add_on_id":{"type":["string","null"],"format":"uuid","description":"Required when item_type=add_on."},"seat_id":{"type":["string","null"],"format":"uuid","description":"Reserved-seat binding; when present, quantity must be 1 and seat_hold_owner is required at the order level."},"quantity":{"type":"integer","minimum":1}}},"OrderAttendeeInput":{"type":"object","description":"ENG-733. Who one ticket is for. Send one entry per ticket when the ticket's event requires attendee details.","required":["ticket_tier_id","first_name","last_name"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid","description":"Ticket type this person holds. Must be a ticket type in the order. Entries for the same ticket type are matched in array order."},"seat_id":{"type":["string","null"],"format":"uuid","description":"Reserved seats only: the seat this person sits in. Must be a seat in the order. Null or omitted for general admission."},"first_name":{"type":"string","minLength":1,"maxLength":60,"description":"1 to 60 characters after trimming."},"last_name":{"type":"string","minLength":1,"maxLength":60,"description":"1 to 60 characters after trimming."},"email":{"type":["string","null"],"format":"email","maxLength":254,"description":"Optional. With an email, the ticket is issued to this person and they get their own pass email. Absent, null or blank means no email: the ticket stays with the buyer under this person's name. When present it must be a valid email. Stored trimmed and lower-cased."}}},"OrderAttendee":{"type":"object","description":"ENG-733. One attendee the buyer entered at checkout.","required":["ticket_tier_id","seat_id","first_name","last_name","email"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"seat_id":{"type":["string","null"],"format":"uuid","description":"Set for a reserved-seat ticket, else null."},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":["string","null"],"description":"Trimmed and lower-cased. Null when the buyer gave no email for this ticket; the ticket then stays with the buyer."}}},"AttendeeDetailsRequiredDetail":{"type":"object","description":"ENG-733. One row per ticket type (or seat) whose attendee count is wrong. Sent with `attendee_details_required`.","required":["ticket_tier_id","seat_id","expected","received"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"seat_id":{"type":["string","null"],"format":"uuid"},"expected":{"type":"integer","minimum":0,"description":"Attendees this ticket type or seat needs."},"received":{"type":"integer","minimum":0,"description":"Attendees the request sent for it."}}},"AttendeeDetailsInvalidDetail":{"type":"object","description":"ENG-733. One row per bad value. Sent with `attendee_details_invalid`.","required":["index","field","ticket_tier_id","seat_id"],"properties":{"index":{"type":"integer","minimum":0,"description":"Position of the entry in the `attendees` array you sent."},"field":{"type":"string","enum":["first_name","last_name","email","ticket_tier_id","seat_id"],"description":"Which value to fix. `ticket_tier_id` or `seat_id` means the entry names a ticket type or seat that is not in the order. `email` only when an email was given and is not valid."},"ticket_tier_id":{"type":["string","null"],"format":"uuid"},"seat_id":{"type":["string","null"],"format":"uuid"}}},"AttendeeDetailsError":{"type":"object","description":"ENG-733. 400 body when the attendees on an order create are missing or invalid. `message` is a sentence safe to show the buyer. The shape of `details` depends on `error`.","required":["success","error","message","details"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","enum":["attendee_details_required","attendee_details_invalid"],"description":"`attendee_details_required`: a ticket that needs an attendee has none, or the count for a ticket type or seat is wrong. `attendee_details_invalid`: a value is invalid, or an entry names a ticket type or seat that is not in the order. A missing or blank email is never an error."},"message":{"type":"string","description":"attendee_details_required: \"Enter a first and last name for every ticket.\" attendee_details_invalid: \"Check the name and email entered for each ticket.\""},"details":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/AttendeeDetailsRequiredDetail"},{"$ref":"#/components/schemas/AttendeeDetailsInvalidDetail"}]}}}},"OrderPreviewLine":{"type":"object","properties":{"item_type":{"type":"string","enum":["ticket","add_on"]},"ticket_tier_id":{"type":["string","null"],"format":"uuid"},"add_on_id":{"type":["string","null"],"format":"uuid"},"quantity":{"type":"integer"},"unit_price_cents":{"type":"integer"},"subtotal_cents":{"type":"integer"},"addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The add-on fee on this line (per ticket or pass, times quantity; 0 on $0 tickets and add-on items). Inside the line's platform fee."},"addon_fee_payer":{"$ref":"#/components/schemas/AddonFeePayer"}}},"AddonFeePayer":{"type":"string","enum":["producer","platform"],"description":"ENG-3310. Who pays the add-on fee on a ticket type or pass: producer = guests pay it on top (default), platform = the organizer absorbs it. AXYN receives the same amount either way."},"OrderPreviewTotal":{"type":"object","description":"HF-001 preview: the exact money shape of a candidate cart, equal to the committed order total. No order is created and no inventory is reserved.","properties":{"subtotal_cents":{"type":"integer"},"discount_cents":{"type":"integer","description":"Coupon discount applied to the ticket portion of the cart (0 when no coupon). subtotal_cents keeps face value; the buyer charge is subtotal - discount (+ fees) + tax."},"coupon_codes":{"type":"array","items":{"type":"string"},"description":"Echo of the applied coupon codes (normalized uppercase, allocation order); empty when no coupons."},"platform_fee_cents":{"type":"integer"},"processing_fee_cents":{"type":"integer","description":"All card processing on the charge, tax included, at processing_rate_basis. Part of fees_cents."},"absorbed_processing_fee_cents":{"type":"integer","description":"ENG-1921. The part of processing_fee_cents the organizer absorbs; not in total_cents. Guests see only processing_fee_cents − absorbed_processing_fee_cents."},"venue_fee_cents":{"type":"integer","minimum":0,"description":"ENG-1724 the event's named venue fee across this order, in cents. Inside total_cents and inside the all-in price a guest is quoted, but never part of fees_cents, which stays AXYN's own take. No AXYN fee is charged on it."},"venue_fee_label":{"type":["string","null"],"description":"Which kind of venue fee this is (restoration, preservation, facility, venue_improvement). Null when the event charges none."},"venue_fee_reason":{"type":["string","null"],"description":"The one line guests read under the fee, for example \"Restores this 1937 theatre\"."},"fees_cents":{"type":"integer"},"tax_cents":{"type":"integer","description":"Sales tax in cents (0 when non-taxable / Case 1). Itemized at checkout; excluded from application_fee."},"taxable_base_cents":{"type":"integer","description":"Portion of the cart subject to sales tax before rate application."},"tax_rate_bps":{"type":"integer","description":"Event sales-tax rate in basis points (850 = 8.50%). 0 when not taxable."},"total_cents":{"type":"integer"},"ticket_qty":{"type":"integer"},"currency":{"type":"string"},"channel":{"type":"string","enum":["direct","affiliate"]},"fee_payer":{"type":["string","null"],"enum":["producer","platform",null],"description":"Derived. producer or platform when every ticket line matches; null for mixed carts. Never trust a client-supplied fee_payer."},"processing_fee_payer":{"type":["string","null"],"enum":["producer","platform",null],"description":"ENG-1921. Derived like fee_payer: who carries card processing; null for mixed carts."},"processing_rate_basis":{"type":"string","enum":["standard","cash"],"description":"ENG-1921 / ENG-2096. How this total's processing settles. Every payment method, cash at the door included, is priced at the one published rate, so the total is the same on every method and never changes after the payment method is entered. standard = an electronic charge (card, Apple Pay, Google Pay, ACH); the processing true-up settles the processor's actual fee with the organizer. cash = cash at entry: no processor, the organizer keeps the Service fee."},"charged_platform_fee_cents":{"type":"integer","description":"Platform fee included in the buyer charge (excludes absorbed lines)."},"addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The negotiated add-on fee across the cart, 100% AXYN revenue. Inside platform_fee_cents (so AXYN's own fee is platform_fee_cents − addon_fee_cents). Outside the fee cap and the free first event."},"charged_addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The part of addon_fee_cents guests pay on top (inside charged_platform_fee_cents and total_cents). Guest lines: when addon_fee_description is set, show charged_addon_fee_cents as its own line named addon_fee_name and the Ticketing fee as charged_platform_fee_cents − charged_addon_fee_cents; otherwise it stays inside the Ticketing fee (charged_platform_fee_cents). Never inside the Service fee."},"addon_fee_name":{"type":["string","null"],"maxLength":32,"description":"ENG-3310. The add-on fee's short guest name, snapshotted on the order. Null when the event has no add-on fee or no name."},"addon_fee_description":{"type":["string","null"],"description":"ENG-3310. The add-on fee's public description (the fee explainer), snapshotted on the order. Non-null means guests see the add-on fee as its own line."},"stripe_connect_account_id":{"type":["string","null"],"description":"Connected Stripe account for deferred Payment Element mount. Present so card fields can load before a PaymentIntent or hold is created."},"stripe_publishable_key":{"type":["string","null"],"description":"Stripe publishable key for the mode the PaymentIntent will be opened in (test for a sandbox tenant). The deferred Payment Element mounts with this key and stripe_connect_account_id before any order exists; a site env key is only a fallback for an API that omits it."},"payment_method_types":{"type":"array","items":{"type":"string"},"description":"Exact Stripe payment_method_types the PaymentIntent for this cart's payment_method will carry (ENG-1629 allowlist: card rail → [\"card\"], ACH rail → [\"us_bank_account\"]; empty for cash_at_entry). A deferred Payment Element (mode: payment, no clientSecret) must pass this list verbatim as paymentMethodTypes, or stripe.confirmPayment fails because Elements collected with automatic payment methods."},"wallets":{"$ref":"#/components/schemas/CheckoutWallets"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderPreviewLine"}},"discount_lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderPreviewDiscountLine"},"description":"ENG-1888: one line per applied source per ticket type."},"offer_hints":{"type":"array","items":{"$ref":"#/components/schemas/OfferHint"}},"code_not_applied_reason":{"type":["string","null"],"enum":["automatic_better",null],"description":"Set when an automatic discount saves more than the entered code(s); the code is accepted but not redeemed. Not an error."},"codes_not_applied":{"type":"array","items":{"type":"string"},"description":"Entered codes that were accepted but not applied or redeemed."}}},"UpgradePaymentStart":{"type":"object","required":["payment_intent_id","client_secret","due_now_cents","stripe_connect_account_id","stripe_publishable_key"],"properties":{"payment_intent_id":{"type":"string"},"client_secret":{"type":["string","null"]},"due_now_cents":{"type":"integer"},"stripe_connect_account_id":{"type":["string","null"],"description":"Connected Stripe account the PaymentIntent lives on (direct charge). Pass it to Stripe.js as stripeAccount. Null when the intent is on the platform (sandbox tenants, test mode)."},"stripe_publishable_key":{"type":["string","null"],"description":"Stripe publishable key for the mode the PaymentIntent was opened in (test for a sandbox tenant). Mount Stripe.js with this key, not a site env key."},"wallets":{"$ref":"#/components/schemas/CheckoutWallets"}}},"CheckoutWallets":{"type":"object","description":"Which wallets the organizer lets buyers use (Settings › Payments, How buyers can pay). Pass it to your Stripe Payment Element as the `wallets` option: { applePay: wallets.apple_pay, googlePay: wallets.google_pay, link: wallets.link }. Cards are always accepted. AXYN cannot apply it on a partner's page; your payment form must. Changes apply on the next page load.","required":["apple_pay","google_pay","link"],"properties":{"apple_pay":{"type":"string","enum":["auto","never"]},"google_pay":{"type":"string","enum":["auto","never"]},"link":{"type":"string","enum":["auto","never"],"description":"Saved card (Link). never unless the organizer turns it on."}}},"PaymentView":{"type":"object","properties":{"method":{"$ref":"#/components/schemas/PaymentMethod"},"provider":{"type":["string","null"]},"payment_intent_id":{"type":["string","null"]},"client_secret":{"type":["string","null"]},"stripe_connect_account_id":{"type":["string","null"],"description":"Connected Stripe account the PaymentIntent lives on (direct charge). Pass it to Stripe.js as stripeAccount. Null when the intent is on the platform (sandbox tenants, test mode)."},"stripe_publishable_key":{"type":["string","null"],"description":"Stripe publishable key for the mode the PaymentIntent was opened in (test for a sandbox tenant). Mount Stripe.js with this key, not a site env key."},"status":{"type":["string","null"]},"wallets":{"description":"The organizer's How buyers can pay switches for this payment form. Null when no payment form is needed (a $0 order).","oneOf":[{"$ref":"#/components/schemas/CheckoutWallets"},{"type":"null"}]}}},"TicketStatus":{"type":"string","enum":["pending","active","transferred","redeemed","refunded","cancelled","voided"]},"EventTicket":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"ticket_tier_id":{"type":"string","format":"uuid"},"ticket_number":{"type":"string"},"qr_code":{"type":"string"},"qr_issued_at":{"type":"string","format":"date-time"},"qr_expires_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/TicketStatus"},"payment_status":{"type":"string"},"total_paid_cents":{"type":"integer"},"purchased_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"pickup":{"$ref":"#/components/schemas/TicketBadgePickup"}},"description":"Abbreviated; the API returns the full event_tickets row (transfer/refund/guest fields included)."},"TicketBadgePickup":{"type":"object","description":"ENG-1563. Present on buyer tickets (order read, Live Pass) for badge pickup ticket types. Render guest_copy verbatim so confirmation, Live Pass, and email match.","required":["fulfillment_policy","pickup_requires_scan","pickup_required_before_admit","pickup_id_check_required","pickup_location_label","pickup_address","pickup_instructions","pickup_opens_at","pickup_closes_at","pickup_completed","timezone","guest_copy"],"properties":{"fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"Snapshot at issue."},"pickup_requires_scan":{"type":"boolean","description":"Snapshot at issue. False: staff check the guest in when they hand the badge over."},"pickup_required_before_admit":{"type":"boolean","description":"Snapshot at issue."},"pickup_id_check_required":{"type":"boolean","description":"Snapshot at issue."},"pickup_location_label":{"type":["string","null"],"description":"Live desk location."},"pickup_address":{"type":["string","null"],"description":"Live desk street address when away from the event address."},"pickup_instructions":{"type":["string","null"],"description":"Live organizer note."},"pickup_opens_at":{"type":["string","null"],"format":"date-time"},"pickup_closes_at":{"type":["string","null"],"format":"date-time"},"pickup_completed":{"type":"boolean","description":"True after staff record the badge handoff. The handoff checks the guest in only when pickup_requires_scan is false."},"timezone":{"type":["string","null"],"description":"Event IANA time zone used for guest_copy hours."},"guest_copy":{"type":["object","null"],"required":["status","heading","lines","directions_url"],"properties":{"status":{"type":"string","enum":["to_pick_up","picked_up"]},"heading":{"type":"string"},"lines":{"type":"array","items":{"type":"string"}},"directions_url":{"type":["string","null"],"format":"uri","description":"Maps link when the desk has its own address."}}}}},"TicketTier":{"type":"object","properties":{"on_sale":{"type":"boolean","description":"Series catalog read (GET /v1/productions/{productionId}) only: whether this type can be bought now, by the rule order create applies. A pass is on sale while its own window is open and at least one show it admits is on sale. A listed type may be false, for example a presale that has not opened."},"id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"currency":{"type":"string"},"price_cents":{"type":"integer"},"min_per_order":{"type":"integer"},"max_per_order":{"type":["integer","null"]},"inventory_total":{"type":"integer"},"inventory_reserved":{"type":"integer"},"inventory_sold":{"type":"integer"},"inventory_refunded":{"type":"integer"},"tickets_held":{"type":"integer","description":"Staff JWT only: tickets guests still hold for this ticket type or pass (active, transferred or scanned; never refunded, cancelled, voided or unpaid). The admin asks before raising a minimum age when this is above zero."},"sales_start_at":{"type":["string","null"],"format":"date-time"},"sales_end_at":{"type":["string","null"],"format":"date-time"},"sort_order":{"type":"integer"},"is_active":{"type":"boolean"},"is_hidden":{"type":"boolean"},"allow_multiple_coupons":{"type":"boolean","description":"When true on every tier in a cart, buyers may stack multiple distinct coupon codes in one checkout. Default false."},"fee_payer":{"type":"string","enum":["producer","platform"],"description":"Who pays the AXYN platform fee for this type. producer = buyer pays (default). platform = organizer absorbs the AXYN fee. Card processing has its own choice, processing_fee_payer. Not buyer-writable."},"processing_fee_payer":{"type":"string","enum":["producer","platform"],"description":"ENG-1921 — who pays card processing for this type. producer = guests pay it on top of the price (default when omitted). platform = the organizer absorbs it out of the price. Independent of fee_payer (the AXYN fee). Card processing is a pass-through: AXYN nets $0.00 on it. A change applies to new orders only. Not buyer-writable."},"addon_fee_payer":{"$ref":"#/components/schemas/AddonFeePayer"},"fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"ENG-1563. How the guest gets the thing. digital (default) is a QR on the phone. will_call (envelope or paper ticket) and badge (printed credential) are handed over at a pickup desk and put every ticket on this type onto the will-call roster."},"pickup_requires_scan":{"type":"boolean","description":"ENG-1563 optional scan gate. True (default) keeps the door scan mandatory after pickup. False means handing the item over at the desk checks the guest in (audited as a manual admit) and forces pickup_required_before_admit; only settable on a will_call or badge type."},"pickup_required_before_admit":{"type":"boolean","description":"ENG-1563. When true, online scan and manual admit return pickup_required until badge handoff."},"pickup_id_check_required":{"type":"boolean","description":"ENG-1563. Staff must attest photo ID at pickup. Never stores ID data."},"pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"ENG-1563. The spot guests look for, e.g. North gate, white tent."},"pickup_reminder_enabled":{"type":"boolean","description":"ENG-1563. Email guests the day before the desk opens. Default true."},"pickup_address":{"type":["string","null"],"maxLength":300,"description":"ENG-1563. Street address only when the desk is not at the event address. Guests get a directions link."},"pickup_instructions":{"type":["string","null"],"maxLength":1000},"pickup_opens_at":{"type":["string","null"],"format":"date-time"},"pickup_closes_at":{"type":["string","null"],"format":"date-time"},"re_entry_policy":{"type":"string","enum":["no_reentry","n_times","unlimited","exit_stamped"],"description":"ENG-1920. Door re-entry for this ticket type or pass. no_reentry admits once; n_times admits up to re_entry_limit entries in total, first entry included; unlimited re-admits on every scan. exit_stamped is legacy (scans alternate exit and entry) and is not settable. The door reads the setting from the ticket it admits, so a pass's setting wins for anyone admitted on that pass. Online scan, the offline door pack and manual admit enforce it the same way."},"pickup_follows_event":{"type":"boolean","description":"This ticket type's pickup settings are a copy of its event's Entry & check-in default and change with it. A new occurrence type with no pickup fields follows; sending pickup fields sets false; true re-copies the event (409 badge_pickup_locked_by_sales if that turns off a desk with sales). Not allowed on a pass (400 entry_follows_event_not_on_pass)."},"pickup_follows_series":{"type":"boolean","description":"Series pass only: its pickup settings are a copy of the series default and change with it. A new pass with no pickup fields follows; sending pickup fields sets false; true re-copies the series (409 badge_pickup_locked_by_sales if that turns off a desk with sales). 400 follows_series_pass_only on a day ticket."},"re_entry_follows_series":{"type":"boolean","description":"Series pass only: its re-entry is a copy of the series default. A new pass with no re-entry fields follows; sending re_entry_* sets false."},"sales_follow_series":{"type":"boolean","description":"Series pass only: its sales window is a copy of the series sales window. A new pass with no sales_start_at / sales_end_at follows; sending either sets false."},"re_entry_follows_event":{"type":"boolean","description":"This ticket type's re-entry is a copy of its event's default and changes with it. A new occurrence type with no re_entry_policy follows; sending re_entry_policy sets false; true re-copies the event. Not allowed on a pass."},"re_entry_limit":{"type":["integer","null"],"minimum":1,"description":"ENG-1920. Total entries allowed when re_entry_policy is n_times (first entry included). Null for every other policy."},"section_id":{"type":["string","null"],"format":"uuid","description":"Venue section this type sells in for section_and_type events. Null when unassigned or reserved-seat."},"section_name":{"type":["string","null"],"description":"ENG-1217. Linked area name stamped on catalog GET."},"location_note":{"type":["string","null"],"maxLength":120,"description":"ENG-1217. Where they sit, stamped from venue_section."},"area_remaining":{"type":"integer","minimum":0,"description":"Guest catalog reads (GET /v1/events/{eventId}/tiers and, ENG-3017, GET /v1/productions/{productionId}): seats left that this type can sell. On a type linked to an area (section_id set), it is the area's seats left, the same number on every type sharing that area, and the type's inventory_total / inventory_available report that area (inventory_available = area_remaining; inventory_total = area_remaining + this type's own sold and held). Count a shared area once. Also set when the show's capacity caps this type below its own count, or when a series pass holds seats on the show. Omitted when the type's own inventory is the whole answer."},"show_remaining":{"type":"integer","minimum":0,"description":"ENG-3303. Catalog reads (GET /v1/events/{eventId}/tiers, guest and staff, and GET /v1/productions/{productionId}): seats left on the whole show when the show has a capacity, after every day ticket, pass-held seat and claim block. Present on every day-ticket type of that show with the same number: those types share this one limit, so a reader adding types' seats left counts it once: cap the sum at show_remaining. Omitted when the show has no capacity, and on pass types."},"show_capacity":{"type":"integer","minimum":0,"description":"ENG-3303. The show's capacity, sent exactly when show_remaining is: the seats in all that show_remaining is counted against."},"low_inventory_truthful":{"type":"boolean","description":"HF-003: server-computed; true only when remaining inventory is under the 20% ceiling and recent sales velocity exceeds the per-event threshold. Never settable by a partner."},"perks":{"type":"array","items":{"$ref":"#/components/schemas/TierPerk"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tier_scope":{"type":"string","enum":["occurrence","pass"],"description":"occurrence = single show; pass = multi-occurrence production pass (ENG-138)."},"production_id":{"type":["string","null"],"format":"uuid","description":"Production parent when tier_scope is pass."},"pass_coverage":{"type":"string","enum":["shows","all","days"],"description":"Series pass only: what it opens. shows = the listed admits (a fixed list; every pass created before this field). all = every show in the series; days = every show on pass_coverage_days (each show's own calendar day). For all and days the API writes the admits: a show added to the series later (or given a place) joins, and people who already bought get it. A show never leaves on its own. An all/days pass with its own sales_start_at may go on sale before its shows' own sales open, once one show it opens is published."},"pass_coverage_days":{"type":["array","null"],"items":{"type":"string","format":"date"},"maxItems":60,"description":"With pass_coverage = days: the calendar days (YYYY-MM-DD) the pass opens. Null otherwise."},"admits":{"type":"array","description":"Catalog pass admit rows (production_pass_admits). Present on pass tiers when listing or after create/replace.","items":{"$ref":"#/components/schemas/PassTierAdmitInput"}},"claimable_sessions":{"type":"array","description":"ENG-2341. Guest catalog reads only (`GET /v1/productions/{productionId}` and `GET /v1/events/{eventId}/tiers` with an API key), on pass types only: the sessions this pass lets its holder claim after buying, soonest first. Empty: the pass has nothing to claim. Absent on other ticket types. Each session is named here whatever `lineup_on_series_page` says, because it is part of what the pass offers; programs the pass does not claim stay hidden when the lineup is hidden. A session is listed only while claiming is on for it and its program is on sale or sold out.","items":{"$ref":"#/components/schemas/PassClaimableSession"}},"claim_limit_total":{"type":["integer","null"],"minimum":1,"description":"ENG-2341. With `claimable_sessions`: how many sessions one pass may hold a claim on at once. Null when the pass has nothing to claim."},"restricted_sessions_count":{"type":"integer","minimum":0,"description":"ENG-2344. Guest catalog reads, pass types only. How many of the programs this pass opens are shown only to holders of chosen pass types, this pass among them (\"Includes 2 sessions shown only to VIP Pass holders\"). No program is named. Sent whether or not `lineup_on_series_page` is on. 0 when the pass sees none, and when the series shows no lineup to ticket holders. Draft and cancelled programs are not counted."},"restricted_sessions_pass_names":{"type":"array","items":{"type":"string"},"description":"ENG-2344. With `restricted_sessions_count`: the names of the pass types that see those programs, this pass among them, in name order. Empty when the count is 0."},"offers":{"type":"array","items":{"$ref":"#/components/schemas/TierOffer"},"description":"Catalog reads only (ENG-1888): automatic discounts on this ticket type."}}},"PassClaimableSession":{"type":"object","description":"ENG-2341. One session a pass lets its holder claim, as a guest reads it before buying. The terms are the ones the live pass claim area applies after purchase.","required":["occurrence_event_id","title","starts_at","doors_open","timezone","venue_name","minimum_age","must_claim","price_cents","currency","claim_opens_at","claim_closes_at","max_claims_per_pass","is_full","guest_note"],"properties":{"occurrence_event_id":{"type":"string","format":"uuid","description":"The session's program (event id)."},"title":{"type":"string","description":"The session's own name, also when the series hides its lineup."},"starts_at":{"type":["string","null"],"format":"date-time"},"doors_open":{"type":["string","null"],"format":"date-time"},"timezone":{"type":["string","null"],"description":"IANA zone guests see the program in."},"venue_name":{"type":["string","null"]},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"The program's minimum age. 0 is all ages."},"must_claim":{"type":"boolean","description":"True: the door turns the pass away at this session without a claim. False: claiming guarantees a place and is included, and an unclaimed pass may still walk in while there is room."},"price_cents":{"type":"integer","minimum":0,"description":"What the holder's card is charged to claim, card processing included: the same amount the live pass claim area shows and charges. 0: included with the pass."},"currency":{"type":"string"},"claim_opens_at":{"type":["string","null"],"format":"date-time","description":"Claiming opens then. Null: open already."},"claim_closes_at":{"type":["string","null"],"format":"date-time","description":"Claiming closes then. Null: no closing time."},"max_claims_per_pass":{"type":"integer","minimum":1,"description":"How many sessions one pass may hold a claim on at once, across every session it can claim (the pass type's `claim_limit_total`). A pass claims any one session once."},"is_full":{"type":"boolean","description":"No claim places are left right now."},"guest_note":{"type":["string","null"],"description":"The organizer's note about claiming this session."}}},"PassTierAdmitInput":{"type":"object","required":["occurrence_event_id"],"properties":{"occurrence_event_id":{"type":"string","format":"uuid","description":"Occurrence event id (event.id or source_venue_event_id)."},"allocation_qty":{"type":"integer","minimum":1,"maximum":1,"description":"Always 1: one ticket admits one person."},"admit_opens_at":{"type":["string","null"],"format":"date-time","description":"Optional per-occurrence admit window override."},"title":{"type":["string","null"],"description":"ENG-1655 catalog read: occurrence title when known. Omit on write.","readOnly":true},"starts_at":{"type":["string","null"],"format":"date-time","description":"ENG-1655 catalog read: occurrence starts_at when known. Omit on write.","readOnly":true},"venue_name":{"type":["string","null"],"description":"ENG-1655 catalog read: occurrence venue_name when known. Omit on write.","readOnly":true}},"additionalProperties":false},"ProductionEventSummary":{"type":"object","required":["id","title","starts_at"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time","description":"Show end when set. Duration is derived by clients; this field is the stored clock."},"doors_open":{"type":["string","null"],"format":"date-time","description":"Doors clock when set and different from start."},"timezone":{"type":["string","null"]},"status":{"type":["string","null"],"description":"Occurrence event status for series date rows (ENG-1637)."},"venue_name":{"type":["string","null"]},"venue_address_line1":{"type":["string","null"],"description":"ENG-2783. Series catalog read: the program's venue street address. Null when the place is not an active AXYN venue."},"venue_city":{"type":["string","null"],"description":"ENG-2783. Series catalog read: the program's venue city."},"venue_region":{"type":["string","null"],"description":"ENG-2783. Series catalog read: the program's venue state or region."},"venue_postal_code":{"type":["string","null"],"description":"ENG-2783. Series catalog read: the program's venue postal code."},"venue_country":{"type":["string","null"],"description":"ENG-2783. Series catalog read: the program's venue country."},"ticketing_layout_mode":{"type":["string","null"]},"source_venue_event_id":{"type":["string","null"],"format":"uuid"},"who_it_is_for_override":{"type":["string","null"],"maxLength":280,"description":"ENG-1663. This show's Who it is for override. Null or omitted when the show inherits the series line. Show this on the show row when present."},"program_note":{"type":["string","null"],"maxLength":160,"description":"The line under this program's name on the series page: the first line of the program's own About (description), as plain text. A line saved through program_note before the About took over still shows when the program has no About."},"excluded_from_passes":{"type":"boolean","description":"Not included in passes: Every show / By day passes skip this show (it sells on its own)."},"shown_in_lineup":{"type":"boolean","description":"ENG-2344. Guest reads only (GET /v1/productions/{productionId} and its `/events`). True when this program's name, image and description are in this response: list only these programs as the lineup. False when the series hides its lineup before purchase, or the program is shown only to holders of chosen pass types or to no one: `title` is the series title, `hero_image_url`, `program_note` and `who_it_is_for_override` are null, and its id, status, day, time, place and age stay so its tickets still list and sell."},"guest_visibility":{"type":"string","enum":["everyone","passes","no_one"],"description":"ENG-2344. Organizer (staff) reads only. Who can see this program: see `Event.guest_visibility`."},"guest_visibility_passes":{"type":"array","description":"ENG-2344. Organizer (staff) reads only. The pass types chosen for `passes`, for the \"VIP Pass only\" tag. Empty otherwise; `no_one` reads \"Not shown to guests\".","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"on_sale_with_series":{"type":"boolean","description":"True (the default): the series Put on sale includes this program. False: it is held as a draft for a later announcement until it is published on its own. Organizer reads only; buyer catalogs omit it."},"announce_at":{"type":["string","null"],"format":"date-time","description":"Held program: when it is published by itself. Organizer reads only."},"announce_failed_at":{"type":["string","null"],"format":"date-time","description":"The scheduled publish was refused because the program was not ready; it stays a draft until the announce date changes. Organizer reads only."},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. Effective setting for this show: its own value, else the series value. When `required`, tickets for this show need a first and last name each at checkout. An email per ticket is optional."},"attendee_details_mode_override":{"type":["string","null"],"enum":["off","required",null],"description":"ENG-733. This show's own value when it does not follow the series. Null when the show follows the series setting."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. Minimum age shown to guests and door staff: 0 (all ages), 18 or 21. Effective value: the event's own, else its series'. When it is 18 or 21, show guests the age and that they need photo ID. AXYN never checks an age and never blocks a purchase on it."},"minimum_age_override":{"type":["integer","null"],"enum":[0,18,21,null],"description":"ENG-2300. This program's own minimum age when it belongs to a series and has one. Null when it follows the series. Always null for an independent event."}}},"BuyerTenantBrand":{"type":"object","description":"Organizer brand block on buyer payloads (bearer pass, order confirmation, transfer claim preview, upgrade invite).","required":["display_name","kind","powered_by_axyn_required"],"properties":{"display_name":{"type":"string"},"kind":{"type":"string","enum":["direct","aggregator"]},"powered_by_axyn_required":{"type":"boolean"},"support_email":{"type":["string","null"],"format":"email","description":"The one buyer-facing organizer support address: the organizer's guest support inbox (tenant support_email), else their account contact email. Null when neither is set; buyer help then routes to AXYN support. Clients resolve help through this field only."},"contact_email":{"type":["string","null"],"format":"email","deprecated":true,"description":"Deprecated alias of support_email, same value. Present on the transfer claim preview and upgrade invite only, for older SDK builds. Read support_email."},"logo_url":{"type":["string","null"]},"logo_alt":{"type":["string","null"]},"brand_color_hero":{"type":["string","null"]},"brand_color_hero_secondary":{"type":["string","null"]},"brand_color_hero_text":{"type":["string","null"]},"brand_color_hero_text_muted":{"type":["string","null"]},"brand_color_accent":{"type":["string","null"]},"brand_font_display":{"type":["string","null"]},"brand_font_sans":{"type":["string","null"]}}},"SeriesLineupPreview":{"type":"object","required":["surface","when","lineup_shown","reveal_at","series_page","live_pass"],"properties":{"surface":{"type":"string","enum":["series_page","live_pass"]},"when":{"type":"string","enum":["now","after_reveal"]},"lineup_shown":{"type":"boolean","description":"Whether guests see the lineup on this surface in the state previewed."},"reveal_at":{"type":["string","null"],"format":"date-time","description":"The reveal time stored for this surface, past or to come. Organizer only; never sent to a guest."},"series_page":{"type":["object","null"],"additionalProperties":true,"description":"Set for `surface=series_page`: the same object a guest receives as `data` from `GET /v1/productions/{productionId}`, with the same programs left unnamed."},"live_pass":{"oneOf":[{"$ref":"#/components/schemas/SeriesLineupSamplePass"},{"type":"null"}],"description":"Set for `surface=live_pass`."}}},"SeriesLineupSamplePass":{"type":"object","description":"A live pass for a holder who does not exist, with nothing claimed and no seat. `series`, `pass` and `pass_admits` have the shape of the same fields on the live pass lookup.","required":["sample","holder_name","event","tier","timezone","series","pass","pass_admits"],"properties":{"sample":{"type":"boolean","enum":[true]},"holder_name":{"type":"string","enum":["Sample guest"]},"event":{"type":"null"},"tier":{"type":"object","required":["id","name","price_cents","currency"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price_cents":{"type":"integer"},"currency":{"type":"string"}}},"timezone":{"type":["string","null"],"description":"The zone the series' first program shows its times in."},"series":{"type":["object","null"],"required":["title","lineup_on_live_pass"],"properties":{"title":{"type":"string"},"lineup_on_live_pass":{"type":"boolean"}}},"pass":{"type":["object","null"],"required":["valid_from","valid_to","place","minimum_age"],"properties":{"valid_from":{"type":["string","null"],"format":"date-time"},"valid_to":{"type":["string","null"],"format":"date-time"},"place":{"type":["string","null"]},"minimum_age":{"type":"integer","enum":[0,18,21]}}},"pass_admits":{"type":"array","description":"The programs a holder of this pass type sees. Empty when the lineup is hidden from ticket holders.","items":{"$ref":"#/components/schemas/TicketUrlPassAdmitStrip"}}}},"TicketUrlPassAdmitStrip":{"type":"object","required":["occurrence_event_id","title","inventory_kind"],"properties":{"occurrence_event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":["string","null"],"format":"date-time"},"venue_name":{"type":["string","null"]},"inventory_kind":{"type":"string","enum":["ga_allocation","reserved_seat"]},"seat_id":{"type":["string","null"],"format":"uuid"},"admit_opens_at":{"type":["string","null"],"format":"date-time"},"held":{"type":["string","null"],"enum":["claimed","seat",null],"description":"ENG-2337. Why this row is the holder's own: `claimed` (they claimed the session) or `seat` (a seat is reserved for them there). Null: the pass simply admits it. A row that is the holder's own shows whatever the series' lineup setting says."},"visible_to_pass_names":{"type":"array","items":{"type":"string"},"description":"ENG-2344. Set when the holder sees this program because of the pass type they hold: the names of the pass types that see it (\"VIP Pass only\"). Empty for a program every holder sees. A program shown only to other pass types, or to no one, is not in `pass_admits` at all unless `held` is set."}}},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. Minimum age of this show: 0 (all ages), 18 or 21. A pass can open shows with different ages; show the age and the photo ID line on each row that has one."},"AddOn":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"price_cents":{"type":"integer"},"inventory_total":{"type":"integer"},"inventory_reserved":{"type":"integer"},"inventory_sold":{"type":"integer"},"inventory_refunded":{"type":"integer"},"max_per_order":{"type":["integer","null"]},"applies_to":{"type":"string","enum":["order","tier","section"]},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TierPerk":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"tier_id":{"type":"string","format":"uuid"},"label":{"type":"string"},"display_order":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Coupon":{"type":"object","description":"A discount at show scope (venue_event_id) or series scope (production_id), exactly one set. redemption_mode=code: a buyer-entered code (stored uppercase, matched case-insensitively; unique across a series and all its shows). redemption_mode=automatic (ENG-1888): no code; applies by quantity of one ticket type. Values are immutable after save: codes can only be deactivated; automatic discounts can be switched off and on.","properties":{"id":{"type":"string","format":"uuid"},"venue_event_id":{"type":["string","null"],"format":"uuid","description":"Show scope. Null for a series discount."},"ticket_tier_id":{"type":["string","null"],"format":"uuid","description":"Reserved for future tier scoping; always null in v1."},"code":{"type":["string","null"],"description":"Normalized uppercase, max 64 characters, no whitespace. Null for automatic discounts."},"percent_bps":{"type":["integer","null"],"minimum":1,"maximum":9500,"description":"Percent-off in basis points (2000 = 20%). Capped at 9500 (95%). Exactly one of percent_bps / amount_cents / group_price_cents is set."},"amount_cents":{"type":["integer","null"],"minimum":1,"description":"Fixed amount off in cents. Clamped at redemption so a buyer always pays at least 5% of ticket value and no less than $5. With apply_mode=per_ticket, this amount is multiplied by ticket quantity before the floor/cap."},"apply_mode":{"type":"string","enum":["cart_ticket_subtotal","per_ticket"],"description":"How a fixed amount_cents coupon applies. cart_ticket_subtotal (default): once against the cart ticket face subtotal. per_ticket: amount_cents × ticket qty (add-ons excluded). Percent coupons always use cart-subtotal math; create rejects per_ticket without amount_cents."},"max_redemptions":{"type":["integer","null"],"minimum":1,"description":"Required for codes. Null on an automatic discount = unlimited (never locked or counted)."},"max_discounted_tickets":{"type":["integer","null"],"minimum":1,"description":"Codes only: at most this many tickets per order get the discount, the cheapest paid ones first; the rest pay full price. Null = every eligible ticket. Always null on an automatic discount."},"redeemed_count":{"type":"integer","minimum":0},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"production_id":{"type":["string","null"],"format":"uuid","description":"Series scope (ENG-1888). Null for a show discount."},"redemption_mode":{"type":"string","enum":["code","automatic"]},"display_name":{"type":["string","null"],"maxLength":60,"description":"Buyer-facing name of an automatic discount (required for automatic)."},"quantity_mode":{"type":["string","null"],"enum":["per_group","threshold",null]},"min_quantity":{"type":["integer","null"],"minimum":2,"maximum":50},"group_price_cents":{"type":["integer","null"],"minimum":0,"description":"Set price per group of min_quantity (automatic per_group only). Exactly one of percent_bps / amount_cents / group_price_cents is set."},"tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ticket types covered. Empty = all in scope; an event code with none keeps whole-cart behaviour."},"scope":{"type":"string","enum":["event","series"]},"used_count":{"type":"integer","minimum":0,"description":"Orders that used it (not cancelled, expired or failed, nor an internal test order left out of reporting). The redemption limit counts redeemed_count."}}},"AddOnBundleItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"add_on_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"AddOnBundle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"discount_cents":{"type":["integer","null"]},"discount_percent_bps":{"type":["integer","null"]},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AddOnBundleItem"}}}},"Seat":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"row_label":{"type":"string"},"seat_number":{"type":"string"},"status":{"type":"string","enum":["available","held","sold","blocked"]},"held_by":{"type":["string","null"],"format":"uuid"},"hold_expires_at":{"type":["string","null"],"format":"date-time"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SeatMapSeat":{"type":"object","description":"A seat as exposed on the public seat map. Never includes hold ownership/expiry.","properties":{"id":{"type":"string","format":"uuid"},"row_label":{"type":"string"},"seat_number":{"type":"string"},"seat_label":{"type":["string","null"]},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"accessible":{"type":"boolean"},"status":{"type":"string","enum":["available","held","sold","blocked"]},"ticket_tier_id":{"type":["string","null"],"format":"uuid","description":"ENG-649 assigned ticket tier for reserved pricing; null when unassigned."},"restricted":{"type":"boolean","description":"ENG-1131 limited or obstructed view."},"restricted_note":{"type":["string","null"],"maxLength":200},"companion_of_seat_id":{"type":["string","null"],"format":"uuid","description":"Companion points at the accessible parent seat."},"house_hold_id":{"type":["string","null"],"format":"uuid"},"hold_type":{"type":["string","null"],"enum":["house","artist","press","production","access"]},"accessible_released":{"type":"boolean","description":"ENG-1132 leftover accessible chairs may be sold without intent when the release rule is met. Holds are not a sell-out."},"view_still_id":{"type":["string","null"],"format":"uuid","description":"ENG-1153 cluster override, or the section default when the chair has none."}}},"ViewStill":{"type":"object","description":"ENG-1153 organizer view still. Shared section or cluster photo.","required":["id","public_url","coverage_label","source"],"properties":{"id":{"type":"string","format":"uuid"},"public_url":{"type":"string","format":"uri"},"coverage_label":{"type":"string","maxLength":120},"source":{"type":"string","enum":["hosted","linked"]}}},"ViewStillSold":{"type":"object","description":"ENG-1153 guest still. Coverage always names the shared view.","required":["id","public_url","coverage_label"],"properties":{"id":{"type":"string","format":"uuid"},"public_url":{"type":"string","format":"uri"},"coverage_label":{"type":"string","maxLength":120}}},"SeatUpdateFailure":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"},"written_seat_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Chairs written before the failure. Reload the seat map; it is the truth."}}},"SeatUpdateResult":{"type":"object","required":["seats_updated"],"properties":{"seats_updated":{"type":"integer","minimum":0}}},"HouseHold":{"type":"object","description":"Named house hold (House / Artist / Press / Production / Access). List and later GETs never return the raw access code — only create and rotate-code do, once.","required":["id","name","hold_type","has_access_code"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hold_type":{"type":"string","enum":["house","artist","press","production","access"]},"note":{"type":["string","null"]},"has_access_code":{"type":"boolean"},"access_code":{"type":["string","null"],"description":"Plain code, only on create (when with_access_code) and rotate-code. Never listed."}}},"SeatMapSection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"display_order":{"type":"integer"},"capacity":{"type":"integer","minimum":0,"description":"Sellable capacity for section_and_type zones. Reserved charts may still send this alongside seats."},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"color":{"type":["string","null"]},"view_still_id":{"type":["string","null"],"format":"uuid","description":"ENG-1153 section default still."},"location_note":{"type":["string","null"],"maxLength":120,"description":"ENG-1217. Where guests sit versus the stage. One sentence."},"seats":{"type":"array","items":{"$ref":"#/components/schemas/SeatMapSeat"}}}},"SeatMap":{"type":"object","properties":{"sections":{"type":"array","items":{"$ref":"#/components/schemas/SeatMapSection"}},"accessible_release_rule":{"type":"string","enum":["never","when_section_sold","when_price_sold","when_house_sold"],"description":"ENG-1131 leftover accessible chairs stay off the public map unless this rule fires."},"seat_select_default":{"type":"string","enum":["find_n","pick_seat"],"description":"ENG-1131 buyer door. find_n is the default."},"stage_end":{"type":"string","enum":["north","east","south","west"],"nullable":true,"description":"ENG-1674 side of the seat chart the stage is on (north = top, small pos_y). Null = not declared; the maps infer it."},"stills":{"type":"array","items":{"$ref":"#/components/schemas/ViewStillSold"},"description":"ENG-1153 stills referenced by this map."}}},"GroupCandidateSeat":{"type":"object","description":"An available seat returned by the best-available-group search.","properties":{"id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"section_name":{"type":"string"},"row_label":{"type":"string"},"seat_number":{"type":"string"},"seat_label":{"type":["string","null"]},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"accessible":{"type":"boolean"},"view_still_id":{"type":["string","null"],"format":"uuid","description":"ENG-1153 effective still for this chair (cluster override or section default)."}}},"BestAvailableGroupRequest":{"type":"object","required":["n"],"properties":{"n":{"type":"integer","minimum":1,"maximum":50,"description":"Number of seats requested together."},"section_id":{"type":"string","format":"uuid","description":"Optional section to restrict the search to."}}},"BestAvailableGroupResult":{"type":"object","description":"HF-012 group-adjacency result: N contiguous seats when ok=true, otherwise structured alternatives — never a silent non-adjacent partial.","properties":{"ok":{"type":"boolean"},"seats":{"type":"array","items":{"$ref":"#/components/schemas/GroupCandidateSeat"}},"alternatives":{"type":"array","items":{"type":"object","required":["type","label"],"properties":{"type":{"type":"string","enum":["split","best_individual","waitlist"]},"label":{"type":"string"},"seats":{"type":"array","items":{"$ref":"#/components/schemas/GroupCandidateSeat"}},"groups":{"type":"array","items":{"type":"object","properties":{"section_id":{"type":"string","format":"uuid"},"section_name":{"type":"string"},"row_label":{"type":"string"},"seats":{"type":"array","items":{"$ref":"#/components/schemas/GroupCandidateSeat"}}}}}}}},"stills":{"type":"array","items":{"$ref":"#/components/schemas/ViewStillSold"},"description":"ENG-1153 stills for proposed seats and split groups. Find N hides the map."}}},"SeatImportRow":{"type":"object","required":["section_name","row_label","seat_number"],"properties":{"section_name":{"type":"string"},"row_label":{"type":"string"},"seat_number":{"type":"string"},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"seat_label":{"type":["string","null"]},"accessible":{"type":"boolean"}}},"SeatImportResult":{"type":"object","properties":{"sections_touched":{"type":"integer"},"seats_inserted":{"type":"integer"},"seats_updated":{"type":"integer"}}},"SeatReplaceGridResult":{"type":"object","required":["sections_touched","seats_inserted","seats_updated","seats_removed"],"properties":{"sections_touched":{"type":"integer"},"seats_inserted":{"type":"integer"},"seats_updated":{"type":"integer"},"seats_removed":{"type":"integer"}}},"VenueHouseSeat":{"type":"object","required":["row_label","seat_number"],"properties":{"id":{"type":"string","format":"uuid"},"row_label":{"type":"string"},"seat_number":{"type":"string"},"seat_label":{"type":["string","null"]},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"accessible":{"type":"boolean"}}},"VenueHouseSection":{"type":"object","required":["name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"display_order":{"type":"integer"},"capacity":{"type":"integer"},"price_modifier_cents":{"type":"integer"},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"color":{"type":["string","null"]},"seats":{"type":"array","items":{"$ref":"#/components/schemas/VenueHouseSeat"}}}},"VenueHouse":{"type":"object","required":["sections","has_seating"],"description":"Tenant venue house copy (geometry only). Not live event inventory. Apply copies house into an event; save copies the event chart back to the venue. Neither is a live link.","properties":{"has_seating":{"type":"boolean","description":"True after a house has been saved. Overwrite then requires confirm_overwrite=true."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/VenueHouseSection"}}}},"SectionInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"display_order":{"type":"integer"},"capacity":{"type":"integer"},"price_modifier_cents":{"type":"integer"},"pos_x":{"type":["number","null"]},"pos_y":{"type":["number","null"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"color":{"type":["string","null"]},"location_note":{"type":["string","null"],"maxLength":120,"description":"ENG-1217. Where they sit. Required on Approve for sellable areas."}}},"ConnectAccountView":{"type":"object","properties":{"connected":{"type":"boolean"},"external_account_id":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","restricted","disabled","none"]},"charges_enabled":{"type":"boolean"},"payouts_enabled":{"type":"boolean"},"sell_ready":{"type":"boolean","description":"ENG-1567 S1. True when the tenant may take card charges (sandbox, platform-legacy, or live Connect ready). False for leftover/incomplete/unprobeable Connect."},"sell_blocker":{"type":["string","null"],"description":"ENG-1567 S1. Null when sell_ready. connect_incomplete, connect_missing_on_platform, payout_check_unavailable, or tenant_suspended."}}},"WorkspaceDefaults":{"type":"object","description":"ENG-779 typed workspace defaults. Null means the default is unset (system default applies for inheriting drafts).","properties":{"address_collection_mode":{"type":["string","null"],"enum":["postal_only","full",null]},"phone_collection_mode":{"type":["string","null"],"enum":["off","optional","required",null]},"tax_rate_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"tax_not_applicable":{"type":["boolean","null"]},"partner_commerce_pixel_enabled":{"type":["boolean","null"]},"allow_upgrades":{"type":["boolean","null"],"description":"ENG-812 house rule for new drafts. Null means unset (system = upgrades off). Does not write live event paths."},"upgrade_cutoff_hours":{"type":["integer","null"],"minimum":0,"maximum":8760,"description":"Default hours-before-doors cutoff for new suggested paths. Null means no default cutoff. Paths stay per-event."}}},"ScanResult":{"type":"object","description":"Business scan outcome (HTTP 200). result_code is one of the scan/qr codes.","properties":{"result_code":{"type":"string","enum":["valid","already_used","wrong_event","wrong_tenant","refunded","payment_pending","not_yet_valid","expired","revoked","event_cancelled","invalid_qr","scanner_not_authorized","wrong_door","unknown"]},"result_message":{"type":["string","null"],"description":"Human sentence for the door. Present on wrong_door, where it names the station that refused and the door that admits this ticket."},"ticket_id":{"type":["string","null"],"format":"uuid"},"ticket_number":{"type":["string","null"]},"venue_event_id":{"type":["string","null"],"format":"uuid"},"ticket_status":{"type":["string","null"]}}},"ScannerPendingCashOrder":{"type":"object","description":"ENG-1603: an advance pay-at-door order awaiting cash, matched by manual lookup. It has no tickets until POST /v1/scanner/cash-collected. Buyer email is masked.","required":["order_id","order_reference","ticket_count","expected_amount_cents","currency"],"properties":{"order_id":{"type":"string","format":"uuid"},"order_reference":{"type":"string","description":"First 8 characters of the order id, uppercased. The reference printed on the hold email and buyer confirmation."},"buyer_name":{"type":["string","null"]},"buyer_email_masked":{"type":["string","null"]},"ticket_count":{"type":"integer"},"expected_amount_cents":{"type":"integer"},"currency":{"type":"string"},"hold_expires_at":{"type":["string","null"],"format":"date-time"}}},"ScannerManualLookupMatch":{"type":"object","description":"A ticket matched by manual lookup (HF-023). Buyer email is masked.","properties":{"ticket_id":{"type":"string","format":"uuid"},"ticket_number":{"type":"string"},"ticket_status":{"type":"string"},"payment_status":{"type":"string"},"order_id":{"type":["string","null"],"format":"uuid"},"buyer_name":{"type":["string","null"]},"buyer_email_masked":{"type":["string","null"]},"tier_name":{"type":["string","null"]},"fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"ENG-1563 snapshot at issue."},"pickup_requires_scan":{"type":"boolean","description":"ENG-1563 snapshot at issue. False: handing over the badge checks the guest in."},"pickup_required_before_admit":{"type":"boolean"},"pickup_id_check_required":{"type":"boolean"},"pickup_completed":{"type":"boolean"},"pickup_window_open":{"type":"boolean","description":"Server time is inside the live desk hours."},"pickup_hours_label":{"type":["string","null"],"description":"Desk hours in event-local time, same words guests see."}}},"ScannerDevice":{"type":"object","description":"A scanning device registered against an event (T-077 Path B). Enforced only when the event has requires_device_registration enabled.","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"device_id":{"type":"string"},"lane_id":{"type":["string","null"]},"label":{"type":["string","null"]},"registered_by_user_id":{"type":["string","null"],"format":"uuid"},"registered_at":{"type":"string","format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"}}},"BandKeyRequest":{"type":"object","description":"Asks for the event's wristband key on device registration. `challenge` returns a one-time challenge; `deliver` presents the Android key attestation made over it.","required":["step"],"properties":{"step":{"type":"string","enum":["challenge","deliver"]},"attestation_chain":{"type":"array","description":"`deliver` only. The attested wrapping key's X.509 certificate chain, each certificate base64-encoded DER, leaf first, root last.","maxItems":10,"items":{"type":"string","format":"byte","maxLength":10924}}}},"BandKeyChallenge":{"type":"object","required":["challenge","expires_at"],"properties":{"challenge":{"type":"string","format":"byte","description":"32 random bytes, base64. Use the decoded bytes as the key attestation challenge. Single use."},"expires_at":{"type":"string","format":"date-time"}}},"BandKeyDelivery":{"type":"object","required":["wrapped_key","key_version","expires_at"],"properties":{"wrapped_key":{"type":"string","format":"byte","description":"Android `SecureKeyWrapper`, DER, base64. Import it with `WrappedKeyEntry` under the attested wrapping key."},"key_version":{"type":"integer","minimum":1},"expires_at":{"type":"string","format":"date-time","description":"When the imported key stops working (the end of the offline window)."}}},"TicketTransferOfferIssuedResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","share_code","token_id","recipient_email","expires_at","already_issued","email_sent"],"properties":{"token":{"type":"string","description":"Raw claim token (only on first 201; empty on idempotent replay)."},"share_code":{"type":"string","description":"Human-shareable claim credential."},"token_id":{"type":"string","format":"uuid"},"recipient_email":{"type":"string","format":"email"},"expires_at":{"type":"string","format":"date-time"},"already_issued":{"type":"boolean"},"email_sent":{"type":"boolean"}}}}},"GroupSalesRequestSubmitData":{"type":"object","required":["result_code"],"properties":{"result_code":{"type":"string","enum":["group_sales_request_submitted","group_sales_request_already_submitted","ticket_tier_not_found","tier_not_accepting_group_sales","quantity_within_cap","invalid_requester_name","invalid_requester_email","invalid_requester_phone","invalid_quantity_desired","invalid_notes"]},"request_id":{"type":"string","format":"uuid","nullable":true},"tenant_id":{"type":"string","format":"uuid","nullable":true},"venue_event_id":{"type":"string","format":"uuid","nullable":true},"ticket_tier_id":{"type":"string","format":"uuid","nullable":true},"quantity_desired":{"type":"integer","nullable":true},"max_per_order":{"type":"integer","nullable":true},"status":{"type":"string","nullable":true,"description":"submitted | responded | invoiced | converted | declined | closed"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"field":{"type":"string","nullable":true}}},"GroupSalesRequestSubmitEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/GroupSalesRequestSubmitData"}}},"PayoutOutlookUnit":{"type":"object","required":["scope","production_id","event_id","name","currency","ends_at","held_cents","test_order_cents","paid_early_cents","has_paid_early","early_payouts","early_payout_bps","timing","pays_out_at","sends_on","arrives_by","wait_reason","pays_out_at_if_cleared","sends_on_if_cleared","arrives_by_if_cleared","dispute_evidence_due_by"],"properties":{"scope":{"type":"string","enum":["series","event"]},"production_id":{"type":["string","null"],"format":"uuid"},"event_id":{"type":"string","format":"uuid","description":"The standalone event, or the series' first date."},"name":{"type":"string","description":"The series' or event's title."},"currency":{"type":"string"},"ends_at":{"type":"string","format":"date-time","description":"Latest end of the event or its series."},"held_cents":{"type":"integer","description":"Still in the Stripe balance; paid to the bank after the event. What the after-event payout job pays this unit (its offsets applied). 0 for viewer-only roles."},"test_order_cents":{"type":"integer","description":"ENG-2469. Of held_cents (at most it): the You keep of orders AXYN marked as test. Test orders stay in every payout amount: their money moves through Stripe like any sale, so Payouts matches the bank. 0 for viewer-only roles."},"paid_early_cents":{"type":"integer","description":"AXYN early payouts already sent for this unit. 0 for viewer-only roles."},"has_paid_early":{"type":"boolean","description":"Some of it was paid early. Not masked for viewer-only roles."},"early_payouts":{"type":"string","enum":["active","paused","after_event_only"]},"early_payout_bps":{"type":"integer","description":"Share paid early, in basis points; 0 when paid after the event only."},"timing":{"type":"string","enum":["on_date","next_run","waiting","blocked"],"description":"on_date: sent on pays_out_at. next_run: past due, sent on the job's next (hourly) run. waiting: held until wait_reason clears. blocked: the account is blocked (blocked_by)."},"pays_out_at":{"type":["string","null"],"format":"date-time","description":"The job's due date (event end plus delay_days, series-aware); set when timing is on_date."},"sends_on":{"type":["string","null"],"format":"date","description":"ENG-2376. The day the payout is sent: pays_out_at (or now, for next_run) as a UTC day, the way Stripe dates payouts. arrives_by counts from this same day; show both in UTC so every time zone reads the same pair."},"arrives_by":{"type":["string","null"],"format":"date","description":"ENG-2376. When a standard payout sent on pays_out_at (or now, for next_run) usually reaches the bank: 2 US bank business days on the Federal Reserve holiday calendar, as a UTC day. An estimate, worded \"usually arrives by\". Null when the bank timing is unknown (not USD) or there is no send date."},"wait_reason":{"type":["string","null"],"enum":["cancelled","postponed","dispute_open","refund_in_flight",null]},"pays_out_at_if_cleared":{"type":["string","null"],"format":"date-time","description":"ENG-2358. Waiting on a dispute or refund while the job's due date is still ahead: sent on this date if the wait has cleared by then. Null once that date has passed (sent on the run after it clears) and for every other wait."},"sends_on_if_cleared":{"type":["string","null"],"format":"date","description":"ENG-2376. pays_out_at_if_cleared as a UTC day, like sends_on."},"arrives_by_if_cleared":{"type":["string","null"],"format":"date","description":"ENG-2376. The usual arrival (estimate) for a payout sent on pays_out_at_if_cleared."},"dispute_evidence_due_by":{"type":["string","null"],"format":"date-time","description":"ENG-2358. Waiting on a dispute: the earliest evidence deadline Stripe set (evidence_due_by) among its open disputes that is still ahead."}}},"PayoutOutlookEvent":{"type":"object","description":"ENG-2375. One event's money: its series' when it is a show in one (a series is paid as one unit). Amounts are the payout job's own unit, or the order money of the unit's charges in no Stripe payout yet. 0 for viewer-only roles.","required":["event_id","scope","production_id","name","currency","has_sales","unit","in_balance","on_the_way","paid_out"],"properties":{"event_id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["series","event"]},"production_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string","description":"The series' title for a show in a series, else the event's."},"currency":{"type":"string"},"has_sales":{"type":"boolean","description":"Some paid order exists for the unit."},"unit":{"description":"after_event mode: what the payout job still sends for the unit. Null when nothing is left to send, and in stripe_schedule mode.","oneOf":[{"$ref":"#/components/schemas/PayoutOutlookUnit"},{"type":"null"}]},"in_balance":{"type":["object","null"],"description":"stripe_schedule mode: the unit's money in the Stripe balance and in no payout yet, by whether Stripe makes it available by next_payout_on, after it, or on a day not read yet.","required":["in_next_payout_cents","clearing_later_cents","date_unknown_cents","test_order_cents"],"properties":{"in_next_payout_cents":{"type":"integer"},"clearing_later_cents":{"type":"integer"},"date_unknown_cents":{"type":"integer","description":"Stripe's clearing day for it has not been read: in an upcoming payout, no date guessed."},"test_order_cents":{"type":"integer","description":"ENG-2469. Of the three: test orders' You keep."}}},"on_the_way":{"type":["object","null"],"description":"Its money in a payout that has not reached the bank yet.","required":["amount_cents","arrival_date","test_order_cents","tax_cents","you_keep_cents"],"properties":{"amount_cents":{"type":"integer"},"arrival_date":{"type":["string","null"],"format":"date","description":"Stripe's own arrival_date: the earliest on the way, the latest paid out."},"test_order_cents":{"type":"integer","description":"ENG-2469. Of amount_cents: test orders' You keep. Per order on Stripe's schedule; after the event, the unit's test money not still held, on the way first."},"tax_cents":{"type":"integer","description":"ENG-2900. Of amount_cents: the sales tax collected that AXYN's after-event payouts carried (the organizer remits it). 0 on Stripe's schedule."},"you_keep_cents":{"type":"integer","description":"ENG-2900. Of amount_cents: You keep (amount_cents minus tax_cents)."}}},"paid_out":{"type":["object","null"],"description":"Its money already in the bank.","required":["amount_cents","arrival_date","test_order_cents","tax_cents","you_keep_cents"],"properties":{"amount_cents":{"type":"integer"},"arrival_date":{"type":["string","null"],"format":"date","description":"Stripe's own arrival_date: the earliest on the way, the latest paid out."},"test_order_cents":{"type":"integer","description":"ENG-2469. Of amount_cents: test orders' You keep. Per order on Stripe's schedule; after the event, the unit's test money not still held, on the way first."},"tax_cents":{"type":"integer","description":"ENG-2900. Of amount_cents: the sales tax collected that AXYN's after-event payouts carried (the organizer remits it). 0 on Stripe's schedule."},"you_keep_cents":{"type":"integer","description":"ENG-2900. Of amount_cents: You keep (amount_cents minus tax_cents)."}}}}},"PayoutOutlookView":{"type":"object","description":"ENG-2357. Where the organizer's ticket money is, how much, and when it reaches their bank.","required":["mode","blocked_by","delay_days","currency","units","stripe_schedule","event","viewer_masked"],"properties":{"mode":{"type":"string","enum":["after_event","stripe_schedule"],"description":"after_event: AXYN pays each series or event after it ends (manual payouts). stripe_schedule: approved for Stripe's automatic daily, weekly or monthly payouts."},"blocked_by":{"type":["string","null"],"enum":["suspended","staff_hold","no_bank","schedule_unconfirmed",null],"description":"Nothing reaches the bank until this clears. schedule_unconfirmed: neither manual payouts nor a Stripe-confirmed schedule."},"delay_days":{"type":"integer","description":"Days after an event ends that AXYN pays it."},"currency":{"type":"string"},"units":{"type":"array","items":{"$ref":"#/components/schemas/PayoutOutlookUnit"},"description":"Series and events with money in the balance, in payout order. Empty in stripe_schedule mode."},"stripe_schedule":{"type":["object","null"],"required":["interval","weekly_anchor","monthly_anchor","next_payout_on","next_payout_arrives_by","available_cents","pending_cents","clearing","next_payout_cents","clearing_later","on_the_way","test_order_cents","next_payout_test_order_cents"],"properties":{"interval":{"type":"string","enum":["daily","weekly","monthly"]},"weekly_anchor":{"type":["string","null"]},"monthly_anchor":{"type":["integer","null"]},"next_payout_on":{"type":["string","null"],"format":"date","description":"Next day (UTC) Stripe creates a payout."},"next_payout_arrives_by":{"type":["string","null"],"format":"date","description":"ENG-2376. When that payout usually reaches the bank (estimate, as arrives_by). Null when unknown."},"available_cents":{"type":"integer","description":"Stripe pays the whole available balance on that day. 0 for viewer-only roles."},"pending_cents":{"type":"integer","description":"Still clearing at Stripe (the sum of clearing when it is set). 0 for viewer-only roles."},"clearing":{"type":["array","null"],"description":"ENG-2358. Pending money by the day Stripe makes it available, oldest first, from the pending balance transactions (available_on). Null when Stripe's dates could not be read in full, and for viewer-only roles.","items":{"type":"object","required":["available_on","amount_cents","in_next_payout"],"properties":{"available_on":{"type":"string","format":"date","description":"UTC day Stripe makes it available."},"amount_cents":{"type":"integer"},"in_next_payout":{"type":"boolean","description":"Clears on or before next_payout_on, so that payout includes it."}}}},"next_payout_cents":{"type":"integer","description":"ENG-2358. About what the next payout pays: available_cents plus money clearing on or before next_payout_on. 0 for viewer-only roles."},"clearing_later":{"type":["object","null"],"description":"ENG-2358. Money clearing after next_payout_on (a later payout): its total and first and last clearing days. Null when there is none, when clearing is null, and for viewer-only roles.","required":["amount_cents","from","to"],"properties":{"amount_cents":{"type":"integer"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"on_the_way":{"type":["object","null"],"required":["amount_cents","arrival_date","test_order_cents"],"properties":{"amount_cents":{"type":"integer"},"arrival_date":{"type":["string","null"],"format":"date"},"test_order_cents":{"type":"integer","description":"ENG-2469. Of amount_cents: the You keep of test orders whose charge is in this payout. 0 for viewer-only roles."}}},"test_order_cents":{"type":"integer","description":"ENG-2469. Of the balance (available_cents + pending_cents): the You keep of orders AXYN marked as test whose charge is in no payout yet. Test orders stay in every payout amount: their money moves through Stripe like any sale, so Payouts matches the bank. 0 for viewer-only roles."},"next_payout_test_order_cents":{"type":"integer","description":"ENG-2469. Of test_order_cents: what clears by next_payout_on. 0 for viewer-only roles."}}},"event":{"description":"ENG-2375. Set when the request names an event (event_id); else null.","oneOf":[{"$ref":"#/components/schemas/PayoutOutlookEvent"},{"type":"null"}]},"viewer_masked":{"type":"boolean"}}},"SalesAudience":{"type":"object","description":"ENG-2408 B1-B4. A buyer is the account that bought, else the lowercased email (the guest list's key). Under 10 buyers only `buyers` is set (below_minimum). Shares are whole percents computed by the server.","required":["buyers","below_minimum","came_back","home_cities","distance"],"properties":{"buyers":{"type":"integer"},"below_minimum":{"type":"boolean","description":"Fewer than 10 buyers: the card shows its empty state."},"came_back":{"type":["object","null"],"description":"Came back: paid an order for an earlier, different event or series of this organizer before their first order here. An order on one of this event's or series' own shows, or one refunded in full, does not count.","required":["first_time","came_back","first_time_pct","came_back_pct"],"properties":{"first_time":{"type":"integer"},"came_back":{"type":"integer"},"first_time_pct":{"type":"integer"},"came_back_pct":{"type":"integer"}}},"home_cities":{"type":["object","null"],"description":"Only for readers with unmasked, organization-wide guest_list.read (never finance or viewers). Top 4 cities from the checkout postal code, never the IP.","required":["cities","gave_postal_code"],"properties":{"cities":{"type":"array","maxItems":4,"items":{"type":"object","required":["city","region_code","buyers","share_pct"],"properties":{"city":{"type":"string"},"region_code":{"type":["string","null"]},"buyers":{"type":"integer"},"share_pct":{"type":"integer","description":"Of every buyer."}}}},"gave_postal_code":{"type":"integer","description":"Buyers with a checkout postal code on record."}}},"distance":{"type":["object","null"],"description":"From the anonymous distance band on each sale. Buyers with an unknown distance are left out; null when none is known.","required":["known","over_100_miles","over_100_miles_pct"],"properties":{"known":{"type":"integer"},"over_100_miles":{"type":"integer"},"over_100_miles_pct":{"type":"integer"}}}}},"EarlyPayoutsView":{"type":"object","required":["units","viewer_masked"],"properties":{"units":{"type":"array","items":{"$ref":"#/components/schemas/EarlyPayoutUnit"}},"viewer_masked":{"type":"boolean","description":"A viewer-only role: every amount is 0; read the has_* flags."}}},"EarlyPayoutUnit":{"type":"object","required":["scope","production_id","event_id","currency","holdback_bps","payout_bps","status","earned_net_cents","paid_early_cents","paid_out_cents","held_cents","outstanding_cents","has_paid_early","has_held","has_outstanding","next_payout"],"properties":{"scope":{"type":"string","enum":["series","event"],"description":"series = every date, ticket and pass of one production, paid as one unit; event = an event outside a series."},"production_id":{"type":["string","null"],"format":"uuid"},"event_id":{"type":"string","format":"uuid","description":"The standalone event, or the first date of the series."},"currency":{"type":"string"},"holdback_bps":{"type":"integer","minimum":0,"maximum":10000,"description":"Held until after the event, in basis points. 10000 (100%) when no hold was set."},"payout_bps":{"type":"integer","minimum":0,"maximum":10000,"description":"10000 - holdback_bps."},"status":{"type":"string","enum":["active","paused","after_event_only"],"description":"active = early payouts under the hold % reach this unit; paused = a hold below 100% is set but early payouts are paused for now; after_event_only = paid after the event only."},"earned_net_cents":{"type":"integer","description":"Settled sales money early payouts count (after refunds in progress and disputes)."},"paid_early_cents":{"type":"integer"},"paid_out_cents":{"type":"integer","description":"Early and after-event payouts so far."},"held_cents":{"type":"integer","description":"Collected net still on the Stripe balance for this unit."},"outstanding_cents":{"type":"integer","description":"Paid out above what the unit now keeps, still taken from the next payouts; 0 when none."},"has_paid_early":{"type":"boolean"},"has_held":{"type":"boolean"},"has_outstanding":{"type":"boolean"},"next_payout":{"type":"object","required":["kind","estimated_at"],"properties":{"kind":{"type":"string","enum":["early","after_event"]},"estimated_at":{"type":["string","null"],"format":"date-time","description":"Estimate only."}}}}},"PayoutScheduleView":{"type":"object","additionalProperties":false,"required":["interval","weekly_anchor","monthly_anchor","delay_days","synced_at","source","editable","early_payouts_approved","express_dashboard_required","express_dashboard_url","hold"],"properties":{"interval":{"type":["string","null"],"enum":["daily","weekly","monthly","manual",null]},"weekly_anchor":{"type":["string","null"],"enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday",null]},"monthly_anchor":{"type":["integer","null"],"minimum":1,"maximum":31},"delay_days":{"type":["integer","null"]},"synced_at":{"type":["string","null"],"format":"date-time"},"source":{"type":"string","enum":["stripe","mirror","none"]},"editable":{"type":"boolean","description":"False while payouts are on a staff hold, before bank setup, or while the tenant is not approved for early payouts."},"early_payouts_approved":{"type":"boolean","description":"Whether platform staff approved automatic (early) payouts for this tenant. New Connect accounts start false and stay on manual payouts; every organizer interval (daily, weekly, monthly) needs approval."},"express_dashboard_required":{"type":"boolean"},"express_dashboard_url":{"type":"string","format":"uri"},"hold":{"$ref":"#/components/schemas/PayoutHoldPublicView"}}},"PayoutHoldPublicView":{"type":"object","additionalProperties":false,"description":"ENG-1626: staff payout hold as the organizer sees it. While on_hold is true the Stripe payout schedule is pinned to manual and editable is false; only AXYN staff can lift it. The staff note and actor are never exposed here.","required":["on_hold","reason_code","held_at"],"properties":{"on_hold":{"type":"boolean"},"reason_code":{"type":["string","null"],"enum":["fraud_review","chargeback_risk","compliance_review","dispute","other",null]},"held_at":{"type":["string","null"],"format":"date-time"}}},"PayoutScheduleUpdateRequest":{"type":"object","additionalProperties":false,"required":["interval"],"properties":{"interval":{"type":"string","enum":["daily","weekly","monthly"]},"weekly_anchor":{"type":["string","null"],"enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday",null]},"monthly_anchor":{"type":["integer","null"],"minimum":1,"maximum":31}}},"CoverCropFocus":{"type":"object","required":["focus_x","focus_y","zoom"],"additionalProperties":false,"properties":{"focus_x":{"type":"number","minimum":0,"maximum":1,"description":"Horizontal focus 0–1"},"focus_y":{"type":"number","minimum":0,"maximum":1,"description":"Vertical focus 0–1"},"zoom":{"type":"number","minimum":1,"maximum":3,"description":"Zoom 1.00–3.00"}}},"CoverCrops":{"type":"object","required":["listing","page","discover"],"additionalProperties":false,"properties":{"listing":{"$ref":"#/components/schemas/CoverCropFocus"},"page":{"$ref":"#/components/schemas/CoverCropFocus"},"discover":{"$ref":"#/components/schemas/CoverCropFocus"}},"description":"ENG-789 — per-surface framing for the single hero_image_url. Always present on EventDetail; optional on PATCH (all three surfaces required when present)."},"ListingGalleryItem":{"type":"object","description":"ENG-1667 — one asset in a listing gallery. A gallery belongs to a series or an independent event; a child show never carries one.","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","video"]},"image_url":{"type":"string","format":"uri","nullable":true,"description":"Photo bytes for kind=image, or the poster still for kind=video."},"video_embed_url":{"type":"string","format":"uri","nullable":true,"description":"Canonical player URL, safe as an iframe src. Null for kind=image."},"video_provider":{"type":"string","enum":["youtube","vimeo"],"nullable":true},"alt_text":{"type":"string"},"crop":{"$ref":"#/components/schemas/CoverCropFocus"},"width_px":{"type":"integer","nullable":true},"height_px":{"type":"integer","nullable":true},"sort_order":{"type":"integer"}}},"ListingGalleryItemWrite":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["image","video"]},"image_url":{"type":"string","format":"uri","nullable":true,"description":"Must be a URL AXYN stored for this tenant via the images upload."},"video_embed_url":{"type":"string","format":"uri","nullable":true,"description":"YouTube or Vimeo link. AXYN rewrites it to the canonical player URL."},"alt_text":{"type":"string","nullable":true,"maxLength":300},"focus_x":{"type":"number","minimum":0,"maximum":1},"focus_y":{"type":"number","minimum":0,"maximum":1},"zoom":{"type":"number","minimum":1,"maximum":4},"width_px":{"type":"integer","nullable":true},"height_px":{"type":"integer","nullable":true}}},"ClaimableSession":{"type":"object","description":"A session on a series that a pass unlocks by claiming. Claims draw on claim_capacity, which is carved out of the same occurrence capacity ceiling day tickets sell from.","properties":{"id":{"type":"string","format":"uuid"},"occurrence_event_id":{"type":"string","format":"uuid"},"production_id":{"type":"string","format":"uuid"},"is_enabled":{"type":"boolean"},"claim_mode":{"type":"string","enum":["must_claim","optional_rsvp"]},"claim_capacity":{"type":"integer","minimum":0},"claims_taken":{"type":"integer","minimum":0},"claims_remaining":{"type":"integer","minimum":0},"price_cents":{"type":"integer","minimum":0},"currency":{"type":"string"},"claim_opens_at":{"type":"string","format":"date-time","nullable":true},"claim_closes_at":{"type":"string","format":"date-time","nullable":true},"release_closes_at":{"type":"string","format":"date-time","nullable":true},"guest_note":{"type":"string","nullable":true},"eligible_passes":{"type":"array","items":{"type":"object","properties":{"pass_tier_id":{"type":"string","format":"uuid"},"pass_tier_name":{"type":"string"},"max_claims_per_pass":{"type":"integer","minimum":1}}}}}},"ClaimableSessionOffer":{"type":"object","description":"One session this Live Pass may claim, with the guest's own claim state.","properties":{"claimable_session_id":{"type":"string","format":"uuid"},"occurrence_event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time","nullable":true},"venue_name":{"type":"string","nullable":true},"claim_mode":{"type":"string","enum":["must_claim","optional_rsvp"]},"price_cents":{"type":"integer","minimum":0},"charged_cents":{"type":"integer","minimum":0,"description":"What the card would be debited: face price plus the card fee a second charge owes. Equals price_cents when free."},"currency":{"type":"string"},"claim_opens_at":{"type":"string","format":"date-time","nullable":true},"claim_closes_at":{"type":"string","format":"date-time","nullable":true},"release_closes_at":{"type":"string","format":"date-time","nullable":true},"guest_note":{"type":"string","nullable":true},"claims_remaining":{"type":"integer","minimum":0},"claim_id":{"type":"string","format":"uuid","nullable":true},"claim_status":{"type":"string","enum":["pending_payment","claimed"],"nullable":true}}},"AccreditationQuestion":{"type":"object","required":["id","prompt","answer_kind","is_required","options"],"properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string","maxLength":500},"help_text":{"type":"string","nullable":true,"maxLength":300},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","link"]},"is_required":{"type":"boolean"},"sort_order":{"type":"integer"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"value":{"type":"string"},"sort_order":{"type":"integer"}}}}}},"AccreditationQuestionInput":{"type":"object","required":["prompt","answer_kind"],"description":"Send `id` to keep an existing question. Answered questions keep their kind and options; wording and required may change. Omitted unanswered questions are removed.","properties":{"id":{"type":"string","format":"uuid","nullable":true},"prompt":{"type":"string","maxLength":500},"help_text":{"type":"string","nullable":true,"maxLength":300},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","link"]},"is_required":{"type":"boolean","default":false},"options":{"type":"array","maxItems":20,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":120}}}}}},"AccreditationClass":{"type":"object","description":"A role people apply for (Media, Industry, Artist, Sponsor). Belongs to one show (`event_id`) or one series (`production_id`). Approve issues the bound hidden ticket type as an ordinary Live Pass.","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid","nullable":true},"production_id":{"type":"string","format":"uuid","nullable":true},"ticket_tier_id":{"type":"string","format":"uuid"},"ticket_tier_name":{"type":"string"},"comp_hold_id":{"type":"string","format":"uuid","nullable":true,"description":"Optional organizer comp hold that caps and funds approvals."},"issue_hold_id":{"type":"string","format":"uuid","nullable":true,"description":"Hold the class grows by one per approval when no comp hold is bound."},"name":{"type":"string","maxLength":80},"description":{"type":"string","nullable":true,"maxLength":500},"enabled":{"type":"boolean"},"applications_close_at":{"type":"string","format":"date-time","nullable":true},"max_approved":{"type":"integer","nullable":true,"minimum":1},"approvals_remaining":{"type":"integer","nullable":true},"apply_token":{"type":"string","description":"Share link token (axyn_cls_…). Rotate to invalidate."},"apply_url":{"type":"string","nullable":true,"description":"Hosted apply page for this token."},"accepting_applications":{"type":"boolean"},"closed_reason":{"type":"string","enum":["disabled","closed"],"nullable":true},"counts":{"type":"object","properties":{"pending":{"type":"integer"},"waitlisted":{"type":"integer"},"approved":{"type":"integer"},"denied":{"type":"integer"},"withdrawn":{"type":"integer"},"revoked":{"type":"integer"}}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/AccreditationQuestion"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AccreditationClassInput":{"type":"object","properties":{"ticket_tier_id":{"type":"string","format":"uuid","description":"Required on create. Must be hidden (not publicly buyable). Show classes bind a single-show type; series classes bind a series pass."},"name":{"type":"string","maxLength":80,"description":"Required on create."},"description":{"type":"string","nullable":true,"maxLength":500},"enabled":{"type":"boolean"},"applications_close_at":{"type":"string","format":"date-time","nullable":true},"max_approved":{"type":"integer","nullable":true,"minimum":1},"comp_hold_id":{"type":"string","format":"uuid","nullable":true},"questions":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/AccreditationQuestionInput"}}}},"AccreditationApplication":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"class_id":{"type":"string","format":"uuid"},"class_name":{"type":"string"},"event_id":{"type":"string","format":"uuid","nullable":true},"production_id":{"type":"string","format":"uuid","nullable":true},"reference_code":{"type":"string","pattern":"^ACR-[A-Z2-9]{10}$"},"applicant_name":{"type":"string","nullable":true},"applicant_email":{"type":"string","nullable":true},"applicant_organization":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","waitlisted","approved","denied","withdrawn","revoked"]},"issued_ticket_id":{"type":"string","format":"uuid","nullable":true},"applicant_message":{"type":"string","nullable":true,"description":"Last message shown to the applicant."},"decided_at":{"type":"string","format":"date-time","nullable":true},"decided_by_user_id":{"type":"string","format":"uuid","nullable":true},"decided_by_api_key_id":{"type":"string","format":"uuid","nullable":true},"withdrawn_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"answers":{"type":"array","items":{"type":"object","properties":{"question_id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","link"]},"answer_text":{"type":"string","nullable":true},"option_labels":{"type":"array","items":{"type":"string"}}}}},"note_count":{"type":"integer"}}},"AccreditationApplicationDetail":{"allOf":[{"$ref":"#/components/schemas/AccreditationApplication"},{"type":"object","properties":{"ticket_tier_name":{"type":"string"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"body":{"type":"string"},"author_user_id":{"type":"string","format":"uuid","nullable":true},"author_api_key_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"decisions":{"type":"array","items":{"type":"object","properties":{"from_status":{"type":"string","enum":["pending","waitlisted","approved","denied","withdrawn","revoked"]},"to_status":{"type":"string","enum":["pending","waitlisted","approved","denied","withdrawn","revoked"]},"actor_user_id":{"type":"string","format":"uuid","nullable":true},"actor_api_key_id":{"type":"string","format":"uuid","nullable":true},"internal_note":{"type":"string","nullable":true},"applicant_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}]},"AccreditationPublicForm":{"type":"object","properties":{"class_name":{"type":"string"},"description":{"type":"string","nullable":true},"organizer_name":{"type":"string"},"place":{"type":"object","properties":{"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"timezone":{"type":"string","nullable":true}}},"accepting_applications":{"type":"boolean"},"closed_reason":{"type":"string","enum":["disabled","closed"],"nullable":true},"applications_close_at":{"type":"string","format":"date-time","nullable":true},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"help_text":{"type":"string","nullable":true},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","link"]},"is_required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"}}}}}}}}},"AccreditationPublicStatus":{"type":"object","properties":{"reference_code":{"type":"string"},"status":{"type":"string","enum":["pending","waitlisted","approved","denied","withdrawn","revoked"]},"class_name":{"type":"string"},"organizer_name":{"type":"string"},"place":{"type":"object","properties":{"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"timezone":{"type":"string","nullable":true}}},"applicant_name":{"type":"string","nullable":true},"submitted_at":{"type":"string","format":"date-time"},"decided_at":{"type":"string","format":"date-time","nullable":true},"applicant_message":{"type":"string","nullable":true},"live_pass_url":{"type":"string","nullable":true,"description":"Present when approved: the ordinary Live Pass."},"can_withdraw":{"type":"boolean"},"reapply_url":{"type":"string","nullable":true,"description":"Present when denied/withdrawn and the class is still open."}}},"ReleasedSeat":{"type":"object","description":"ENG-1723. Where a released reserved seat went.","required":["seat_id","event_id","ticket_id","to_status","house_hold_id","off_sale_reason"],"properties":{"seat_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"ticket_id":{"type":["string","null"],"format":"uuid"},"to_status":{"type":"string","enum":["available","held","blocked"]},"house_hold_id":{"type":["string","null"],"format":"uuid"},"off_sale_reason":{"type":["string","null"],"enum":["staff","event_cancelled","already_scanned","door_cache",null]}}},"SeatHistoryEntry":{"type":"object","description":"ENG-1723. One release of a reserved seat.","required":["created_at","reason","from_status","to_status","to_house_hold_name","off_sale_reason","note","actor_user_id","ticket_id","order_id"],"properties":{"created_at":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["ticket_voided","ticket_refunded","ticket_cancelled","hold_released","hold_deleted","door_cache_cleared"]},"from_status":{"type":"string"},"to_status":{"type":"string"},"to_house_hold_name":{"type":["string","null"]},"off_sale_reason":{"type":["string","null"]},"note":{"type":["string","null"]},"actor_user_id":{"type":["string","null"],"format":"uuid"},"ticket_id":{"type":["string","null"],"format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid"}}},"SeatReleasePreview":{"type":"object","description":"ENG-1723. What ending these tickets would do to their seats.","required":["seats","house_holds"],"properties":{"seats":{"type":"array","items":{"type":"object","required":["seat_id","ticket_id","label","ticket_type_name","origin_house_hold_id","default_destination"],"properties":{"seat_id":{"type":"string","format":"uuid"},"ticket_id":{"type":["string","null"],"format":"uuid"},"label":{"type":"string","description":"Section, row and seat, e.g. \"Lower Right M 12\"."},"ticket_type_name":{"type":["string","null"]},"origin_house_hold_id":{"type":["string","null"],"format":"uuid"},"default_destination":{"type":"object","required":["to_status","house_hold_id","off_sale_reason"],"properties":{"to_status":{"type":"string","enum":["available","held","blocked"]},"house_hold_id":{"type":["string","null"],"format":"uuid"},"off_sale_reason":{"type":["string","null"],"enum":["staff","event_cancelled","already_scanned","door_cache",null]}}}}}},"house_holds":{"type":"array","description":"The event's named holds, for a staff choice.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"TierOffer":{"type":"object","description":"ENG-1888 automatic quantity discount a buyer gets on this ticket type, with no code. Listed in the order they apply: series first, then show. A show offer that a series offer would always pre-empt is left out.","required":["coupon_id","display_name","scope","quantity_mode","min_quantity","saving_cents"],"properties":{"coupon_id":{"type":"string","format":"uuid"},"display_name":{"type":"string","description":"Organizer-chosen name shown to buyers, e.g. \"Pair price\"."},"scope":{"type":"string","enum":["series","event"]},"quantity_mode":{"type":"string","enum":["per_group","threshold"],"description":"per_group: every complete group of min_quantity of one ticket type is discounted, leftovers full price. threshold: once the order has min_quantity or more of the type, all of them are discounted."},"min_quantity":{"type":"integer","minimum":2,"maximum":50},"percent_bps":{"type":["integer","null"]},"amount_cents":{"type":["integer","null"]},"group_price_cents":{"type":["integer","null"],"description":"Set price for one group of min_quantity (per_group only)."},"saving_cents":{"type":"integer","description":"Saving on the first qualifying min_quantity tickets, e.g. 60000 for 2 for $6,000 on a $3,300 ticket."}}},"OrderPreviewDiscountLine":{"type":"object","description":"ENG-1888 one applied discount source on one ticket type.","properties":{"coupon_id":{"type":"string","format":"uuid"},"display_name":{"type":["string","null"]},"code":{"type":["string","null"],"description":"Null for automatic discounts."},"mode":{"type":"string","enum":["code","automatic"]},"ticket_tier_id":{"type":["string","null"],"format":"uuid"},"quantity":{"type":"integer","description":"Tickets of this type the discount covers."},"discount_cents":{"type":"integer"}}},"OfferHint":{"type":"object","description":"ENG-1888 \"Add N more to save X\" for a ticket type already in the cart.","properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"coupon_id":{"type":"string","format":"uuid"},"display_name":{"type":["string","null"]},"add_quantity":{"type":"integer","minimum":1},"saving_cents":{"type":"integer"}}},"DiscountScopeTier":{"type":"object","description":"A ticket type a discount at this scope may list. A show scope never lists passes.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price_cents":{"type":"integer"},"is_pass":{"type":"boolean"},"show_title":{"type":["string","null"]}}},"OrderDiscount":{"type":"object","description":"ENG-1888 one applied discount on a placed order (automatic name or code).","properties":{"coupon_id":{"type":["string","null"],"format":"uuid"},"display_name":{"type":["string","null"]},"code":{"type":["string","null"]},"mode":{"type":"string","enum":["code","automatic"]},"discount_cents":{"type":"integer"}}}},"responses":{"BadRequest":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Forbidden":{"description":"Authenticated but not permitted (role/scope/tenant mismatch).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TicketUrlRetired":{"description":"`ticket_url_retired`: this link was retired because its credential was exposed. The holder was sent a replacement link. Every other miss on a ticket-url route stays the opaque 404 `ticket_url_not_found` (ENG-1884).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Conflict":{"description":"State conflict (e.g. inventory sold out, seat unavailable, already revoked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"PaymentGatewayError":{"description":"Upstream payment/provider failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"DatabaseBusy":{"description":"The database is busy: a step could not get a connection in time and never ran. Send the same request again after `Retry-After` seconds. An order create keeps the same Idempotency-Key, so the retry replays any order already made. The `error` code is the one that step answers with otherwise.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"PaymentStartGatewayError":{"description":"Upstream payment/provider failure starting payment. Includes HF-019 actionable failure copy for the buyer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"object","properties":{"failure":{"$ref":"#/components/schemas/PaymentFailure"}}}]}}}}}},"paths":{"/v1/summary-emails/unsubscribe":{"get":{"tags":["public"],"summary":"Open a summary email's unsubscribe link (ENG-2404)","operationId":"openSummaryUnsubscribe","description":"Redirects to the web confirm page. Changes nothing: mail scanners open links, so only a POST turns the summary off.","security":[],"parameters":[{"name":"t","in":"query","required":true,"description":"The unsubscribe token from the email: v1.<organizer id>.<subscription id>.<signature>.","schema":{"type":"string","minLength":10,"maxLength":128}}],"responses":{"302":{"description":"Redirect to the confirm page on the buyer web app."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The confirm page's address is not configured."}}},"post":{"tags":["public"],"summary":"Turn off one summary email (RFC 8058 one-click, ENG-2404)","operationId":"unsubscribeSummaryEmail","description":"Sets the token's own subscription to Off; the member's other summaries and digest are unchanged. Mail clients post `List-Unsubscribe=One-Click` (form-encoded); the confirm page posts with no body. A bad or forged token answers 404 and changes nothing.","security":[],"parameters":[{"name":"t","in":"query","required":true,"description":"The unsubscribe token from the email: v1.<organizer id>.<subscription id>.<signature>.","schema":{"type":"string","minLength":10,"maxLength":128}}],"responses":{"200":{"description":"Off (or already off).","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SummaryUnsubscribeView"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/summary-emails/unsubscribe/status":{"get":{"tags":["public"],"summary":"What a summary unsubscribe link covers (ENG-2404)","operationId":"getSummaryUnsubscribeStatus","description":"For the confirm page: the event or series, the organizer and the current cadence. Changes nothing. A bad or forged token answers 404.","security":[],"parameters":[{"name":"t","in":"query","required":true,"description":"The unsubscribe token from the email: v1.<organizer id>.<subscription id>.<signature>.","schema":{"type":"string","minLength":10,"maxLength":128}}],"responses":{"200":{"description":"The subscription the link names.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SummaryUnsubscribeView"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/email-links/{token}":{"get":{"tags":["public"],"summary":"Open an AXYN email link (ENG-2563)","operationId":"openEmailLink","description":"The link in an AXYN email. A fetch is logged as a raw hit and is never counted as a click: only the landing page's report counts (POST /v1/events/{eventId}/email-clicks). Nothing about the request (address, user agent, network) is read or stored. A visible link redirects to its page, carrying `axyn_click_token` only while landing-page reports are on; the hidden link answers 204; an unknown link redirects to the AXYN home page.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":22,"maxLength":64}}],"responses":{"204":{"description":"The hidden link: logged, nothing to show."},"302":{"description":"Redirect to the link's page (or the AXYN home page for an unknown link)."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The link could not be read; try again."}}}},"/v1/events/{eventId}/email-clicks":{"post":{"tags":["public","partner"],"summary":"Report an AXYN email click token from the landing page (ENG-2563)","operationId":"postEmailClickReport","description":"Sent by the landing page's browser code when the page opened from an AXYN email link. Tenant is derived from the event. An unknown token, another organizer's token and a hidden link's token count nothing; a reported token counts at most once. Every outcome answers 202, so a buyer never sees an error. Stores no IP, user agent or visitor id.","security":[{},{"tenantApiKey":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":22,"maxLength":64,"description":"The `axyn_click_token` the page opened with."}}}}}},"responses":{"202":{"description":"Accepted, whatever the token.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"accepted":{"type":"boolean"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/tenants/{tenantId}/email-sends/{emailSendId}/clicks":{"get":{"tags":["tenants"],"summary":"An AXYN email send's Sent / Clicked / Bought (ENG-2563)","operationId":"getEmailSendClicks","description":"Counts only, never a recipient. Clicked counts recipients with a click the landing page confirmed and no automated flag (too fast after delivery, several links at once, or after the hidden link). Bought counts recipients who paid within 7 days after a counted click.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"emailSendId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["sent","clicked","bought","automated_clicks_left_out","raw_hits"],"properties":{"sent":{"type":"integer","minimum":0},"clicked":{"type":"integer","minimum":0},"bought":{"type":"integer","minimum":0},"automated_clicks_left_out":{"type":"integer","minimum":0,"description":"Shown as \"{n} automated clicks left out\"."},"raw_hits":{"type":"integer","minimum":0,"description":"Link fetches; never shown as clicks."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tenants/{tenantId}/summary-emails/me":{"get":{"tags":["tenants"],"summary":"List my Overview summary emails","operationId":"listMySummaryEmails","description":"ENG-2404: staff JWT with a tenant-wide sales_dashboard.read grant (organizer_admin, event_manager, finance, viewer). Every event and series the caller gets a summary email for (cadence not off), by title. For Settings › Notifications.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"My summary emails.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SummarySubscriptionListItem"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tenants/{tenantId}/summary-emails/me/events/{eventId}":{"get":{"tags":["tenants"],"summary":"Read my summary email for an event","operationId":"getMySummaryEmailForEvent","description":"ENG-2404: staff JWT with a tenant-wide sales_dashboard.read grant. The caller's own cadence for this event; off when never set.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"My cadence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SummarySubscription"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"summary_on_series_show: a show inside a series is summarized by its series."}}},"put":{"tags":["tenants"],"summary":"Set my summary email for an event","operationId":"putMySummaryEmailForEvent","description":"ENG-2404: staff JWT with a tenant-wide sales_dashboard.read grant. Sets the caller's own cadence for this event. The This week card's button and Export › Email me a summary write this one value. A super admin without a membership gets 403 summary_requires_membership.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cadence"],"properties":{"cadence":{"$ref":"#/components/schemas/SummaryCadence"}}}}}},"responses":{"200":{"description":"Saved cadence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SummarySubscription"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"summary_on_series_show: a show inside a series is summarized by its series."}}}},"/v1/tenants/{tenantId}/summary-emails/me/series/{productionId}":{"get":{"tags":["tenants"],"summary":"Read my summary email for a series","operationId":"getMySummaryEmailForSeries","description":"ENG-2404: staff JWT with a tenant-wide sales_dashboard.read grant. The caller's own cadence for this series; off when never set.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"My cadence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SummarySubscription"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["tenants"],"summary":"Set my summary email for a series","operationId":"putMySummaryEmailForSeries","description":"ENG-2404: staff JWT with a tenant-wide sales_dashboard.read grant. Sets the caller's own cadence for this series. The This week card's button and Export › Email me a summary write this one value. A super admin without a membership gets 403 summary_requires_membership.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cadence"],"properties":{"cadence":{"$ref":"#/components/schemas/SummaryCadence"}}}}}},"responses":{"200":{"description":"Saved cadence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SummarySubscription"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/discovery/events":{"get":{"tags":["discovery"],"summary":"List on-sale discovery events for the tenant","operationId":"listDiscoveryEvents","description":"ENG-154: public catalog projection. Requires a tenant API key with the discovery:read scope.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"1-indexed page number."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["soonest","price_asc","price_desc","newly_listed","distance"],"default":"soonest"}},{"name":"venue","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by venue slug when projected."},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Fee-inclusive price_summary_low_cents upper bound (e.g. 6000 for Under $60)."}],"responses":{"200":{"description":"Discovery events page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/EventStatus","description":"`paused` when the organizer paused sales, or when AXYN did (see `sales_paused_reason`)."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"},"series_starts_at":{"type":["string","null"],"format":"date-time","description":"ENG-2782. A series card: the start of its first counted program (on sale, with a venue), the first day the card shows. `starts_at` stays the listing's own date, for sort and date filters. Null on an independent event's card."},"series_ends_at":{"type":["string","null"],"format":"date-time","description":"ENG-2782. A series card: the start of its last counted program (on sale, with a venue), the last day the card shows. Null on an independent event's card."},"series_venue_count":{"type":["integer","null"],"description":"ENG-2782. A series card: how many venues its public programs are at (cancelled programs and programs with no venue yet do not count). Null on an independent event's card."},"series_city":{"type":["string","null"],"description":"ENG-2782. A series card: the one city its venues share; null when they are in more than one city or none is known."}},"additionalProperties":true}},"next_cursor":{"type":["string","null"],"description":"Cursor for the next page in cursor mode; null in page mode."},"page":{"type":["integer","null"],"description":"Echo of the requested page; null in cursor mode."},"total_pages":{"type":["integer","null"],"description":"Pages available at this limit; null in cursor mode."},"total_count":{"type":"integer","description":"Listed events matching the query across all pages. A client paging this list must read total_pages or total_count: there is no `total` key here."},"index_projected_at":{"type":["string","null"]},"venue_count":{"type":"integer"},"sort":{"type":"string"},"limit":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/discovery/nearby":{"get":{"tags":["discovery"],"summary":"List discovery events near a lat/lng (ENG-156)","operationId":"listDiscoveryNearby","description":"Geo-ranked discovery list over the discovery_event projection. Requires tenant API key with discovery:read. lat, lng, and radius (meters) are required.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"},"description":"Latitude of the search origin."},{"name":"lng","in":"query","required":true,"schema":{"type":"number"},"description":"Longitude of the search origin."},{"name":"radius","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":"Search radius in meters."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["distance","soonest","price_asc","price_desc","newly_listed"],"default":"distance"}}],"responses":{"200":{"description":"Nearby discovery events page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to list nearby discovery events."}}}},"/v1/discovery/autocomplete":{"get":{"tags":["discovery"],"summary":"Autocomplete events and venues (ENG-155)","operationId":"listDiscoveryAutocomplete","description":"Prefix autocomplete over discovery events and venues. Requires tenant API key with discovery:read.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Autocomplete query prefix."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Autocomplete suggestions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"q":{"type":"string"},"limit":{"type":"integer"},"suggestions":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to autocomplete discovery."}}}},"/v1/discovery/collections/{slug}":{"get":{"tags":["discovery"],"summary":"Get a published editorial discovery collection (ENG-158)","operationId":"getDiscoveryCollection","description":"Returns a published collection by slug plus its curated discovery events. Requires tenant API key with discovery:read.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection with events.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"collection":{"type":"object"},"events":{"type":"array","items":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/EventStatus","description":"`paused` when the organizer paused sales, or when AXYN did (see `sales_paused_reason`)."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"}},"additionalProperties":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load collection."}}}},"/v1/orgs/{slug}/events":{"get":{"tags":["discovery"],"summary":"List discovery events for an organizer storefront (ENG-160 / ENG-522)","operationId":"listOrgDiscoveryEvents","description":"Organizer storefront discovery facet. Requires tenant API key with discovery:read. `data.org` includes public enrichment fields (about, contact, website, socials) when set (ENG-522).","security":[{"tenantApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["soonest","price_asc","price_desc","newly_listed","distance"],"default":"soonest"}}],"responses":{"200":{"description":"Organization discovery events page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"org":{"type":"object"},"events":{"type":"array","items":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/EventStatus","description":"`paused` when the organizer paused sales, or when AXYN did (see `sales_paused_reason`)."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"}},"additionalProperties":true}},"page":{"type":"integer"},"total":{"type":"integer"},"venue_count":{"type":"integer"},"sort":{"type":"string"},"limit":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load organization events."}}}},"/v1/artists/{slug}":{"get":{"tags":["discovery"],"summary":"Get an artist discovery page (ENG-157)","operationId":"getArtist","description":"Active artist page by slug. Requires tenant API key with discovery:read.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Artist page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load artist."}}}},"/v1/artists/{slug}/events":{"get":{"tags":["discovery"],"summary":"List discovery events for an artist (ENG-157)","operationId":"listArtistDiscoveryEvents","description":"Upcoming/on-sale appearances for an artist slug. Requires tenant API key with discovery:read.","security":[{"tenantApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Artist events.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"artist":{"type":"object"},"events":{"type":"array","items":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/EventStatus","description":"`paused` when the organizer paused sales, or when AXYN did (see `sales_paused_reason`)."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"}},"additionalProperties":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load artist events."}}}},"/v1/tenants":{"post":{"tags":["tenants"],"summary":"Self-serve create a tenant (organizer signup)","operationId":"createTenantSelfServe","description":"ENG-282: requires an organizer staff JWT and an Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["display_name"],"properties":{"display_name":{"type":"string","minLength":1,"maxLength":255},"timezone":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string"}}}}}},"responses":{"201":{"description":"Tenant created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Slug taken or tenant creation limit reached."}}}},"/v1/me/staff-memberships":{"get":{"tags":["tenants"],"summary":"List the caller's tenant staff memberships","operationId":"listMyStaffMemberships","description":"ENG-282: requires an organizer staff JWT.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Staff memberships.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/follows":{"get":{"tags":["buyer"],"summary":"List the authenticated buyer follows (ENG-159)","operationId":"listMyFollows","description":"Returns venue/artist/organizer follows for the authenticated buyer (Supabase JWT).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Follow list.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"follows":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Unable to list follows."}}},"post":{"tags":["buyer"],"summary":"Create or update a buyer follow (ENG-159)","operationId":"upsertMyFollow","description":"Upserts a follow for venue|artist|organizer. Returns 201 on create and 200 on update.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_type","target_id"],"properties":{"target_type":{"type":"string","enum":["venue","artist","organizer"]},"target_id":{"type":"string","format":"uuid"},"notify_opt_in":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Follow updated."},"201":{"description":"Follow created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to save follow."}}}},"/v1/me/follows/{id}":{"delete":{"tags":["buyer"],"summary":"Delete a buyer follow (ENG-159)","operationId":"deleteMyFollow","description":"Deletes a follow owned by the authenticated buyer.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Follow deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to delete follow."}}}},"/health":{"get":{"tags":["health"],"summary":"Liveness probe","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"service":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number"},"environment":{"type":"string"}}}}}}}}},"/readyz":{"get":{"tags":["health"],"summary":"Readiness probe","operationId":"getReadyz","security":[],"responses":{"200":{"description":"Data plane configured.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"service":{"type":"string"},"checks":{"type":"object"}}}}}},"503":{"description":"Data plane not configured."}}}},"/v1/venues/{venueId}":{"get":{"tags":["catalog"],"summary":"Read a native venue location (ENG-1617)","operationId":"getVenue","description":"Tenant-scoped read of an AXYN native venue's address and pin. GET never writes. Dual-auth: tenant API key with catalog:read, or staff JWT with event.read plus x-tenant-id. Tenant never from the body. A partner reads it over HTTP to compare linked venue pins.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"venueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Venue location.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"venue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"address_line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load venue."}}}},"/v1/events/{eventId}/tiers":{"get":{"tags":["catalog"],"summary":"List ticket tiers (API key: active buyer tiers; staff JWT: all admin tiers)","operationId":"listEventTiers","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tiers.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ticket_tiers":{"type":"array","items":{"$ref":"#/components/schemas/TicketTier"}},"venue_country":{"type":["string","null"],"description":"Staff JWT only: the event's venue country (ISO 3166-1 alpha-2), so the door's phone field defaults its country code to it. Null when the event has no active venue or it has no country. Never sent on an API-key read."},"phone_collection_mode":{"type":"string","enum":["off","optional","required"],"description":"Staff JWT only: the event's phone collection setting. The door shows its guest phone field only when this is not `off`. Never sent on an API-key read."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load ticket options."}}},"post":{"tags":["catalog"],"summary":"Create a ticket tier (API key: eventId=venue_event_id + body.venue_id; staff: eventId=event.id)","operationId":"createEventTier","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","venue_id","price_cents","inventory_total"],"properties":{"pickup_follows_series":{"type":"boolean","description":"Series pass only: its pickup settings are a copy of the series default and change with it. A new pass with no pickup fields follows; sending pickup fields sets false; true re-copies the series (409 badge_pickup_locked_by_sales if that turns off a desk with sales). 400 follows_series_pass_only on a day ticket."},"re_entry_follows_series":{"type":"boolean","description":"Series pass only: its re-entry is a copy of the series default. A new pass with no re-entry fields follows; sending re_entry_* sets false."},"sales_follow_series":{"type":"boolean","description":"Series pass only: its sales window is a copy of the series sales window. A new pass with no sales_start_at / sales_end_at follows; sending either sets false."},"pass_coverage":{"type":"string","enum":["shows","all","days"],"description":"Series pass only. all / days: the API computes admits from the series (do not send admits with it); 400 pass_coverage_opens_no_shows when no show matches yet (a show needs a place). shows: a fixed list from admits."},"pass_coverage_days":{"type":"array","items":{"type":"string","format":"date"},"minItems":1,"maxItems":60,"description":"Required with pass_coverage = days; refused otherwise."},"name":{"type":"string"},"venue_id":{"type":"string","format":"uuid"},"price_cents":{"type":"integer","minimum":0},"inventory_total":{"type":"integer","minimum":0},"description":{"type":"string"},"currency":{"type":"string"},"min_per_order":{"type":"integer","minimum":1,"description":"Fewest of this type one order may hold (default 1). Min and max equal sells exactly that many. 400 `min_per_order_exceeds_max_per_order`, naming that max as `max_per_order`, when above max_per_order (8 when omitted)."},"max_per_order":{"type":"integer","minimum":1},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"is_hidden":{"type":"boolean"},"allow_multiple_coupons":{"type":"boolean","description":"Opt this tier into multi-coupon stacking at checkout. Default false."},"fee_payer":{"type":"string","enum":["producer","platform"],"description":"Who pays the AXYN platform fee for this type. producer = buyer pays (default). platform = organizer absorbs the AXYN fee. Card processing has its own choice, processing_fee_payer."},"processing_fee_payer":{"type":"string","enum":["producer","platform"],"description":"ENG-1921 — who pays card processing for this type. producer = guests pay it on top of the price (default when omitted). platform = the organizer absorbs it out of the price. Independent of fee_payer (the AXYN fee). Card processing is a pass-through: AXYN nets $0.00 on it. A change applies to new orders only. Not buyer-writable."},"addon_fee_payer":{"$ref":"#/components/schemas/AddonFeePayer"},"tier_scope":{"type":"string","enum":["occurrence","pass"],"default":"occurrence"},"sales_start_at":{"type":["string","null"],"format":"date-time","description":"Start of this type's own sale window: ISO timestamp, or null for no limit; omit to leave it as is. A pass sells while now is inside its window and at least one show it admits is on sale; the show a pass is stored on does not gate it. Refused with tier_sales_time_invalid (not a timestamp) or tier_sales_window_invalid (end before start)."},"sales_end_at":{"type":["string","null"],"format":"date-time","description":"End of this type's own sale window. Same rules as sales_start_at."},"admits":{"type":"array","description":"Required when tier_scope is pass. Host occurrence must be included.","items":{"$ref":"#/components/schemas/PassTierAdmitInput"}},"fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"ENG-1563. How the guest gets the thing. digital (default) is a QR on the phone. will_call (envelope or paper ticket) and badge (printed credential) are handed over at a pickup desk and put every ticket on this type onto the will-call roster."},"pickup_requires_scan":{"type":"boolean","description":"ENG-1563 optional scan gate. True (default) keeps the door scan mandatory after pickup. False means handing the item over at the desk checks the guest in (audited as a manual admit) and forces pickup_required_before_admit; only settable on a will_call or badge type."},"pickup_required_before_admit":{"type":"boolean","description":"ENG-1563. Door returns pickup_required until the badge is handed over. Forced true when pickup_requires_scan is false."},"pickup_id_check_required":{"type":"boolean","description":"ENG-1563. Staff attest photo ID at pickup. No ID data is stored."},"pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"ENG-1563. Required on will_call or badge. The spot guests look for, e.g. North gate, white tent."},"pickup_address":{"type":["string","null"],"maxLength":300,"description":"ENG-1563. Street address only when the desk is not at the event address."},"pickup_instructions":{"type":["string","null"],"maxLength":1000},"pickup_opens_at":{"type":["string","null"],"format":"date-time","description":"ENG-1563. Required on will_call or badge; before pickup_closes_at."},"pickup_closes_at":{"type":["string","null"],"format":"date-time"},"pickup_reminder_enabled":{"type":"boolean","description":"ENG-1563. Email guests the day before the desk opens. Default true."},"re_entry_policy":{"type":"string","enum":["no_reentry","n_times","unlimited"],"description":"ENG-1920. Door re-entry for this ticket type or pass. Omitted on create means unlimited for a series pass or a ticket type on a show in a series (production), and no_reentry for a ticket type on a standalone show. Send re_entry_limit with n_times. A change applies at the door to tickets already sold on this type."},"pickup_follows_event":{"type":"boolean","description":"This ticket type's pickup settings are a copy of its event's Entry & check-in default and change with it. A new occurrence type with no pickup fields follows; sending pickup fields sets false; true re-copies the event (409 badge_pickup_locked_by_sales if that turns off a desk with sales). Not allowed on a pass (400 entry_follows_event_not_on_pass)."},"re_entry_follows_event":{"type":"boolean","description":"This ticket type's re-entry is a copy of its event's default and changes with it. A new occurrence type with no re_entry_policy follows; sending re_entry_policy sets false; true re-copies the event. Not allowed on a pass."},"re_entry_limit":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"ENG-1920. Required (1 to 1000) when re_entry_policy is n_times: total entries allowed, first entry included. Null or omitted for any other policy. Only accepted together with re_entry_policy."}}}}}},"responses":{"201":{"description":"Tier created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/TicketTier"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/{eventId}/tiers/fee-quote":{"post":{"tags":["catalog"],"summary":"Quote Buyer pays / You keep for a ticket type (staff/API key)","operationId":"quoteEventTierFee","description":"Same assemble path as checkout, qty=1, the published processing rate, tax excluded. Quotes both choices: who pays the AXYN fee (fee_payer) and who pays card processing (processing_fee_payer). Organizer calculator only. Never buyer-writable.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price_cents"],"properties":{"price_cents":{"type":"integer","minimum":0},"fee_payer":{"type":"string","enum":["producer","platform"]},"processing_fee_payer":{"type":"string","enum":["producer","platform"],"description":"ENG-1921. Default producer (guests pay card processing)."},"addon_fee_payer":{"$ref":"#/components/schemas/AddonFeePayer"},"admits":{"type":"array","maxItems":100,"description":"Series pass only: the nights it admits (the tier write shape). The quote then includes each admitted night's venue fee, as checkout charges a pass.","items":{"type":"object","required":["occurrence_event_id"],"properties":{"occurrence_event_id":{"type":"string","format":"uuid"}}}}}}}}},"responses":{"200":{"description":"Fee quote (tax excluded).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"buyer_pays_cents":{"type":"integer"},"you_keep_cents":{"type":"integer","description":"What the guest pays − AXYN fee − all card processing (tax excluded)."},"platform_fee_cents":{"type":"integer"},"processing_fee_cents":{"type":"integer"},"absorbed_processing_fee_cents":{"type":"integer","description":"ENG-1921. Card processing the organizer absorbs (0 when guests pay it)."},"addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The event's add-on fee on this one ticket (0 when none or a $0 ticket). Inside platform_fee_cents: the AXYN fee alone is platform_fee_cents − addon_fee_cents."},"charged_addon_fee_cents":{"type":"integer","minimum":0,"description":"ENG-3310. The part guests pay on top (addon_fee_cents when addon_fee_payer is producer, else 0)."},"addon_fee_name":{"type":["string","null"],"maxLength":32,"description":"ENG-3310. The add-on fee's name, for the read-only line in event setup. Null when none."},"addon_fee_description":{"type":["string","null"],"description":"ENG-3310. The add-on fee's public description. Null when none."},"processing_rate_basis":{"type":"string","enum":["standard","cash"],"description":"ENG-1921. Always standard: the one published processing rate."},"absorb_exceeds_charge":{"type":"boolean","description":"Fees the organizer would cover exceed what they receive (You keep < 0). The admin disables that choice; checkout raises absorb_exceeds_charge."},"tax_excluded":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/tiers/{tierId}":{"patch":{"tags":["catalog"],"summary":"Update a ticket tier","operationId":"updateEventTier","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup_follows_series":{"type":"boolean","description":"Series pass only: its pickup settings are a copy of the series default and change with it. A new pass with no pickup fields follows; sending pickup fields sets false; true re-copies the series (409 badge_pickup_locked_by_sales if that turns off a desk with sales). 400 follows_series_pass_only on a day ticket."},"re_entry_follows_series":{"type":"boolean","description":"Series pass only: its re-entry is a copy of the series default. A new pass with no re-entry fields follows; sending re_entry_* sets false."},"sales_follow_series":{"type":"boolean","description":"Series pass only: its sales window is a copy of the series sales window. A new pass with no sales_start_at / sales_end_at follows; sending either sets false."},"pass_coverage":{"type":"string","enum":["shows","all","days"],"description":"Series pass only. all / days: the API computes admits from the series (do not send admits with it); 400 pass_coverage_opens_no_shows when no show matches yet (a show needs a place). shows: a fixed list from admits."},"pass_coverage_days":{"type":"array","items":{"type":"string","format":"date"},"minItems":1,"maxItems":60,"description":"Required with pass_coverage = days; refused otherwise."},"admit_times":{"type":"array","minItems":1,"description":"ENG-3339. Series pass only: when this pass starts admitting at each show it opens (`admit_opens_at`). Works with every pass_coverage, without restating what the pass opens. The scan refuses the pass before its time with `not_yet_valid`; its time wins over the show's `doors_open`. Null clears a show's time (the show's door time applies). Shows not listed keep theirs; a time for a show the pass does not open is not stored. 400 `admit_time_show_not_in_series` when a show is not in the pass's series. Tickets already sold keep the entry time they were bought with.","items":{"type":"object","required":["occurrence_event_id","admit_opens_at"],"properties":{"occurrence_event_id":{"type":"string","format":"uuid"},"admit_opens_at":{"type":["string","null"],"format":"date-time"}}}},"name":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string"},"price_cents":{"type":"integer","minimum":0},"min_per_order":{"type":"integer","minimum":1,"description":"Fewest of this type one order may hold (default 1). Min and max equal sells exactly that many. 400 `min_per_order_exceeds_max_per_order`, naming that max as `max_per_order`, when it would be above the sent max_per_order, else the stored one, else 8."},"max_per_order":{"type":"integer","minimum":1},"inventory_total":{"type":"integer","minimum":0},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"is_hidden":{"type":"boolean"},"allow_multiple_coupons":{"type":"boolean","description":"Opt this tier into multi-coupon stacking at checkout. Default false."},"fee_payer":{"type":"string","enum":["producer","platform"],"description":"Who pays the AXYN platform fee for this type. producer = buyer pays (default). platform = organizer absorbs the AXYN fee. Card processing has its own choice, processing_fee_payer."},"processing_fee_payer":{"type":"string","enum":["producer","platform"],"description":"ENG-1921 — who pays card processing for this type. producer = guests pay it on top of the price (default when omitted). platform = the organizer absorbs it out of the price. Independent of fee_payer (the AXYN fee). Card processing is a pass-through: AXYN nets $0.00 on it. A change applies to new orders only. Not buyer-writable."},"addon_fee_payer":{"$ref":"#/components/schemas/AddonFeePayer"},"sales_start_at":{"type":["string","null"],"format":"date-time","description":"Start of this type's own sale window: ISO timestamp, or null for no limit; omit to leave it as is. A pass sells while now is inside its window and at least one show it admits is on sale; the show a pass is stored on does not gate it. Refused with tier_sales_time_invalid (not a timestamp) or tier_sales_window_invalid (end before start)."},"sales_end_at":{"type":["string","null"],"format":"date-time","description":"End of this type's own sale window. Same rules as sales_start_at."},"admits":{"type":"array","description":"Replace catalog pass admits (production_pass_admits only; sold tickets keep event_ticket_pass_admits snapshots). Pass tiers only. Leaving out the show the pass is stored on moves that storage anchor to the earliest show kept that is not cancelled.","items":{"$ref":"#/components/schemas/PassTierAdmitInput"}},"fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"ENG-1563. How the guest gets the thing. digital (default) is a QR on the phone. will_call (envelope or paper ticket) and badge (printed credential) are handed over at a pickup desk and put every ticket on this type onto the will-call roster."},"pickup_requires_scan":{"type":"boolean","description":"ENG-1563 optional scan gate. True (default) keeps the door scan mandatory after pickup. False means handing the item over at the desk checks the guest in (audited as a manual admit) and forces pickup_required_before_admit; only settable on a will_call or badge type."},"pickup_required_before_admit":{"type":"boolean","description":"ENG-1563. Door returns pickup_required until the badge is handed over. Forced true when pickup_requires_scan is false."},"pickup_id_check_required":{"type":"boolean","description":"ENG-1563. Staff attest photo ID at pickup. No ID data is stored."},"pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"ENG-1563. Required on will_call or badge. The spot guests look for, e.g. North gate, white tent."},"pickup_address":{"type":["string","null"],"maxLength":300,"description":"ENG-1563. Street address only when the desk is not at the event address."},"pickup_instructions":{"type":["string","null"],"maxLength":1000},"pickup_opens_at":{"type":["string","null"],"format":"date-time","description":"ENG-1563. Required on will_call or badge; before pickup_closes_at."},"pickup_closes_at":{"type":["string","null"],"format":"date-time"},"pickup_reminder_enabled":{"type":"boolean","description":"ENG-1563. Email guests the day before the desk opens. Default true."},"re_entry_policy":{"type":"string","enum":["no_reentry","n_times","unlimited"],"description":"ENG-1920. Door re-entry for this ticket type or pass. Omitted on create means unlimited for a series pass or a ticket type on a show in a series (production), and no_reentry for a ticket type on a standalone show. Send re_entry_limit with n_times. A change applies at the door to tickets already sold on this type."},"pickup_follows_event":{"type":"boolean","description":"This ticket type's pickup settings are a copy of its event's Entry & check-in default and change with it. A new occurrence type with no pickup fields follows; sending pickup fields sets false; true re-copies the event (409 badge_pickup_locked_by_sales if that turns off a desk with sales). Not allowed on a pass (400 entry_follows_event_not_on_pass)."},"re_entry_follows_event":{"type":"boolean","description":"This ticket type's re-entry is a copy of its event's default and changes with it. A new occurrence type with no re_entry_policy follows; sending re_entry_policy sets false; true re-copies the event. Not allowed on a pass."},"re_entry_limit":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"ENG-1920. Required (1 to 1000) when re_entry_policy is n_times: total entries allowed, first entry included. Null or omitted for any other policy. Only accepted together with re_entry_policy."}}}}}},"responses":{"200":{"description":"Tier updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/TicketTier"},"unticked_programs":{"type":"array","description":"ENG-2344. Programs this pass type was chosen to see (`guest_visibility: passes`) and no longer opens after this write. It was unticked from each in the same write. Empty when none.","items":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"pass_expand_reserved_seat_refused: the pass already has holders and a show it would add is reserved-seat (seats cannot be assigned to existing holders); or capacity_ceiling_blocked when a show it would add has no room for them.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}},"delete":{"tags":["catalog"],"summary":"Delete a ticket tier (refused when inventory_sold > 0)","operationId":"deleteEventTier","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tier deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Tier has sold inventory and cannot be deleted."}}}},"/v1/events/tiers/{tierId}/archive":{"post":{"tags":["catalog"],"summary":"Archive a ticket tier nobody holds a ticket on (ENG-2294)","operationId":"archiveEventTier","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The archived tier.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/TicketTier"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"tier_has_reserved_inventory: something is still held on the tier (an unpaid order or a comp hold). tier_has_live_tickets: a ticket on the tier is still pending, active, transferred or redeemed (a refund in progress counts until it completes).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}},"description":"Takes a ticket type or series pass out of Setup and off every buyer surface for good, keeping its orders and refunds. Allowed when nothing is held on it (inventory_reserved is 0) and every ticket issued on it is refunded, cancelled or voided. The tier is kept with is_active false and is_hidden true; it cannot be bought or restored. Archiving an already archived tier succeeds."}},"/v1/events/tiers/{tierId}/pickup-notice":{"get":{"tags":["catalog"],"summary":"Preview the badge pickup change notice (ENG-1563)","operationId":"previewBadgePickupChangeNotice","description":"After editing a badge pickup ticket type that has sold, shows who would be emailed (live tickets not yet picked up, one email per holder) and the exact email rendered from the current desk details. Sends nothing.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Preview.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"recipients":{"type":"integer"},"tickets":{"type":"integer"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"tier_not_found (unknown, other tenant, or not a badge pickup type)."}}},"post":{"tags":["catalog"],"summary":"Send the badge pickup change notice (ENG-1563)","operationId":"sendBadgePickupChangeNotice","description":"Organizer-confirmed. Queues one transactional email per holder with the current desk details and Live Pass links. Idempotent per details version: repeating it for unchanged details returns duplicates and sends nothing new.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"recipients":{"type":"integer"},"queued":{"type":"integer"},"duplicates":{"type":"integer"},"errors":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"tier_not_found."}}}},"/v1/events/tiers/{tierId}/perks":{"post":{"tags":["catalog"],"summary":"Add a perk to a ticket tier","operationId":"createTierPerk","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"display_order":{"type":"integer","minimum":0}}}}}},"responses":{"201":{"description":"Perk created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"perk":{"$ref":"#/components/schemas/TierPerk"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/tiers/{tierId}/perks/{perkId}":{"patch":{"tags":["catalog"],"summary":"Update a tier perk","operationId":"updateTierPerk","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"perkId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"display_order":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Perk updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"perk":{"$ref":"#/components/schemas/TierPerk"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["catalog"],"summary":"Delete a tier perk","operationId":"deleteTierPerk","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"perkId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Perk deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/{eventId}/coupons":{"get":{"tags":["catalog"],"summary":"List coupons for an event (organizer-only; requires catalog:write scope or event.write staff permission)","operationId":"listEventCoupons","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Coupons.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"coupons":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"}},"series_overlaps":{"type":"array","description":"Active series automatic discounts that cover this show's ticket types (they apply first).","items":{"type":"object","properties":{"coupon_id":{"type":"string","format":"uuid"},"display_name":{"type":["string","null"]},"tier_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}},"ticket_tiers":{"type":"array","items":{"$ref":"#/components/schemas/DiscountScopeTier"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"failed to load coupons"}}},"post":{"tags":["catalog"],"summary":"Create a show discount: a code or an automatic quantity discount (API key: eventId=venue_event_id; staff: eventId=event.id).","operationId":"createEventCoupon","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","maxLength":64,"description":"Trimmed and uppercased server-side; no whitespace. Unique among active codes per event (case-insensitive)."},"percent_bps":{"type":"integer","minimum":1,"maximum":9500,"description":"Percent-off in basis points; max 9500 (95%). Provide exactly one of percent_bps / amount_cents."},"amount_cents":{"type":"integer","minimum":1,"description":"Fixed amount off in cents. Provide exactly one of percent_bps / amount_cents."},"apply_mode":{"type":"string","enum":["cart_ticket_subtotal","per_ticket"],"default":"cart_ticket_subtotal","description":"Fixed-amount apply mode. Default cart_ticket_subtotal. per_ticket requires amount_cents and multiplies by ticket qty at redemption."},"max_redemptions":{"type":"integer","minimum":1,"description":"Codes: required, total orders that may redeem. Automatic: optional; omit for unlimited."},"max_discounted_tickets":{"type":"integer","minimum":1,"description":"Codes only: at most this many tickets per order get the discount, the cheapest paid ones first; the rest pay full price. Omit for every eligible ticket. An order still counts as one use."},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","description":"Must be after starts_at when both are set."},"redemption_mode":{"type":"string","enum":["code","automatic"],"default":"code"},"display_name":{"type":"string","minLength":1,"maxLength":60},"quantity_mode":{"type":"string","enum":["per_group","threshold"]},"min_quantity":{"type":"integer","minimum":2,"maximum":50},"group_price_cents":{"type":"integer","minimum":0,"description":"per_group only; must be less than min_quantity x the price of every covered ticket type."},"tier_ids":{"type":"array","maxItems":200,"items":{"type":"string","format":"uuid"},"description":"Ticket types to cover (in scope only; a show scope never lists passes). Empty = all."}},"description":"Code mode (default): code + max_redemptions required, one of percent_bps / amount_cents. Automatic mode (redemption_mode=automatic): display_name, quantity_mode, min_quantity and exactly one of percent_bps / amount_cents / group_price_cents required; no code; max_redemptions optional (empty = unlimited). Refusals are 400 with `field` naming the input."}}}},"responses":{"201":{"description":"Coupon created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"coupon":{"$ref":"#/components/schemas/Coupon"},"warnings":{"type":"array","items":{"type":"string","enum":["below_order_floor"]},"description":"Non-blocking: a covered ticket type would price an order under the $5 floor, so the discount is reduced there."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"coupon_code_exists, or coupon_code_in_use when the code is active on the series or one of its shows (`detail` says where)."}}}},"/v1/events/coupons/{couponId}":{"patch":{"tags":["catalog"],"summary":"Switch a discount off (codes: permanent) or, for an automatic discount, back on. Values are immutable.","operationId":"deactivateEventCoupon","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"couponId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["is_active"],"properties":{"is_active":{"type":"boolean","enum":[false,true],"description":"Codes: only false (permanent; is_active=true is rejected with coupon_reactivation_not_allowed). Automatic discounts: true or false. Any other field is rejected with coupon_immutable."}}}}}},"responses":{"200":{"description":"Coupon deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"coupon":{"$ref":"#/components/schemas/Coupon"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["catalog"],"summary":"Delete a coupon (only while redeemed_count = 0)","operationId":"deleteEventCoupon","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"couponId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Coupon deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"coupon_has_redemptions — the coupon has been redeemed and can no longer be deleted; deactivate it instead."}}}},"/v1/events/{eventId}/add-ons":{"get":{"tags":["catalog"],"summary":"List add-ons (API key: active for venue_event_id; staff JWT: all for event.id)","operationId":"listEventAddOns","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Add-ons.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"add_ons":{"type":"array","items":{"$ref":"#/components/schemas/AddOn"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load add-ons."}}},"post":{"tags":["catalog"],"summary":"Create an add-on (eventId = event.id)","operationId":"createEventAddOn","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer","minimum":0},"inventory_total":{"type":"integer","minimum":0},"max_per_order":{"type":"integer","minimum":1},"applies_to":{"type":"string","enum":["order","tier","section"]},"default_state":{"type":"string","enum":["opt_out"]},"is_skippable":{"type":"boolean"},"is_active":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Add-on created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"add_on":{"$ref":"#/components/schemas/AddOn"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/add-ons/{addOnId}":{"patch":{"tags":["catalog"],"summary":"Update an add-on","operationId":"updateEventAddOn","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"addOnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer","minimum":0},"inventory_total":{"type":"integer","minimum":0},"max_per_order":{"type":"integer","minimum":1},"applies_to":{"type":"string","enum":["order","tier","section"]},"default_state":{"type":"string","enum":["opt_out"]},"is_skippable":{"type":"boolean"},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Add-on updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"add_on":{"$ref":"#/components/schemas/AddOn"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["catalog"],"summary":"Delete an add-on (refused when inventory_sold > 0)","operationId":"deleteEventAddOn","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"addOnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Add-on deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Add-on has sold inventory and cannot be deleted."}}}},"/v1/events/{eventId}/bundles":{"get":{"tags":["catalog"],"summary":"List add-on bundles for an event (with items)","operationId":"listEventBundles","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bundles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"bundles":{"type":"array","items":{"$ref":"#/components/schemas/AddOnBundle"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load bundles."}}},"post":{"tags":["catalog"],"summary":"Create an add-on bundle (exactly one discount field)","operationId":"createEventBundle","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"discount_cents":{"type":"integer","minimum":1},"discount_percent_bps":{"type":"integer","minimum":1,"maximum":10000},"is_active":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Bundle created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"bundle":{"$ref":"#/components/schemas/AddOnBundle"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/bundles/{bundleId}":{"patch":{"tags":["catalog"],"summary":"Update an add-on bundle","operationId":"updateEventBundle","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"bundleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"discount_cents":{"type":"integer","minimum":1},"discount_percent_bps":{"type":"integer","minimum":1,"maximum":10000},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Bundle updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"bundle":{"$ref":"#/components/schemas/AddOnBundle"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["catalog"],"summary":"Delete an add-on bundle (cascades to its items)","operationId":"deleteEventBundle","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"bundleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bundle deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/bundles/{bundleId}/items":{"post":{"tags":["catalog"],"summary":"Add an add-on to a bundle","operationId":"addBundleItem","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"bundleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["add_on_id"],"properties":{"add_on_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Bundle item added.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/AddOnBundleItem"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/bundles/{bundleId}/items/{itemId}":{"delete":{"tags":["catalog"],"summary":"Remove an item from a bundle","operationId":"deleteBundleItem","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"bundleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bundle item removed.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean","const":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/{eventId}/seat-map":{"get":{"tags":["catalog"],"summary":"Get the full seat map for a reserved-seat event","operationId":"getEventSeatMap","description":"A buyer API key (catalog:read) reads its own tenant's events in any status, and another organizer's event only while it is public (on_sale or sold_out), the same organizer resolution as GET /v1/events/{eventId}. Draft, cancelled or unknown events of another organizer, and sandbox organizers on the hosted buyer surface, return 404 event_not_found. Hold ownership and expiry are never exposed.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"$ref":"#/components/parameters/AccessCodeHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Seat map (sections + seats with geometry + live status).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatMap"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load seat map."}}}},"/v1/events/{eventId}/best-available-group":{"post":{"tags":["catalog"],"summary":"Find N adjacent seats (HF-012 group-adjacency guarantee)","operationId":"findBestAvailableGroup","description":"Same organizer resolution as GET /v1/events/{eventId}/seat-map: the key tenant's own events, or another organizer's public (on_sale or sold_out) event; anything else is 404 event_not_found.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestAvailableGroupRequest"}}}},"responses":{"200":{"description":"Either N contiguous seats (ok=true) or structured alternatives (ok=false).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/BestAvailableGroupResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid n or section_id."},"500":{"description":"Unable to search for seats."}}}},"/v1/events/{eventId}/seats:update":{"post":{"tags":["catalog"],"summary":"Bulk update reserved seats (tier / block / hold / honesty)","description":"ENG-649 / ENG-736 / ENG-1131. Assign or clear ticket_tier_id, set status to available|blocked|held (staff_comp or house_hold), toggle accessible/restricted, pair companions, or park onto a named house hold. Refuses sold and checkout-held seats. Companion must be the same event. Cross-tenant ids return 404 with no extra hint. Clears seating_ready on success.","operationId":"updateEventSeats","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seat_ids"],"properties":{"seat_ids":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"string","format":"uuid"}},"ticket_tier_id":{"type":["string","null"],"format":"uuid","description":"Tier id for this event, or null to unassign."},"status":{"type":"string","enum":["available","blocked","held"],"description":"held is durable staff Hold for comps (hold_kind=staff_comp). Checkout holds cannot be overwritten."},"accessible":{"type":"boolean"},"restricted":{"type":"boolean"},"restricted_note":{"type":["string","null"],"maxLength":200},"companion_of_seat_id":{"type":["string","null"],"format":"uuid"},"house_hold_id":{"type":["string","null"],"format":"uuid"},"view_still_id":{"type":["string","null"],"format":"uuid","description":"ENG-1153 cluster override. Null clears to the section default. Other tenant 404. Other event 422."}}}}}},"responses":{"200":{"description":"Update result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatUpdateResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"seats_not_mutable (sold or checkout-held), held_below_issued, or tier_not_active (staff-held chairs would create or grow a comp hold on an archived or turned-off ticket type; refused before any chair is written). When some chairs were already written, the body carries written_seat_ids (ENG-1717).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeatUpdateFailure"}}}},"422":{"description":"layout_not_reserved_seat, invalid_tier, or seat_type_required."},"500":{"description":"seat_update_failed. Chairs are written in chunks; written_seat_ids lists any that landed before the failure, and those already count in inventory (ENG-1717).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeatUpdateFailure"}}}}}}},"/v1/events/{eventId}/house-holds":{"get":{"tags":["catalog"],"summary":"List named house holds for an event","description":"ENG-1133. Returns House / Artist / Press / Production / Access holds. Never includes the raw access code. Tenant from the API key or staff JWT. Cross-tenant event id → 404 with no extra hint.","operationId":"listEventHouseHolds","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Named holds. has_access_code is a boolean; the code itself is omitted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/HouseHold"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load holds."}}},"post":{"tags":["catalog"],"summary":"Create a named house hold","description":"ENG-1133. Parks a named hold. with_access_code mints a one-time code that unlocks those chairs at the listed price — not a coupon. Tenant from the API key or staff JWT.","operationId":"createEventHouseHold","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","hold_type"],"properties":{"name":{"type":"string"},"hold_type":{"type":"string","enum":["house","artist","press","production","access"]},"note":{"type":["string","null"]},"with_access_code":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created hold. access_code is present only when with_access_code was true.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/HouseHold"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"invalid_house_hold (missing name or unknown hold_type)."},"500":{"description":"Unable to create hold."}}}},"/v1/events/{eventId}/house-holds/{holdId}/rotate-code":{"post":{"tags":["catalog"],"summary":"Rotate a house-hold access code","description":"ENG-1133. Replaces the code. The previous code stops working. Returns the new plain code once. Cross-tenant hold id → 404 with no extra hint.","operationId":"rotateEventHouseHoldCode","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"New plain access code.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["access_code"],"properties":{"access_code":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to rotate code."}}}},"/v1/events/{eventId}/house-holds/{holdId}/release":{"post":{"tags":["catalog"],"summary":"Release seats on a named house hold","description":"ENG-1133 / ENG-1723. Returns held house_hold seats to open sale in one transaction and records each move in seat history. Sold seats forget the hold as their origin, so a later refund sends them to open sale. The hold row stays. Ticket-type counts resync. Cross-tenant hold id → 404 with no extra hint.","operationId":"releaseEventHouseHold","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Seats on this hold are available again.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["released","seats_released","by_ticket_type"],"properties":{"released":{"type":"boolean"},"seats_released":{"type":"integer","minimum":0},"by_ticket_type":{"type":"array","items":{"type":"object","required":["ticket_tier_id","name","seats"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"seats":{"type":"integer","minimum":1}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to release hold."}}}},"/v1/events/{eventId}/house-holds/{holdId}":{"delete":{"tags":["catalog"],"summary":"Delete a named house hold","description":"ENG-1133 / ENG-1723. Releases the hold's seats like release, then removes the hold. Cross-tenant hold id → 404 with no extra hint.","operationId":"deleteEventHouseHold","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Hold deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["deleted","seats_released","by_ticket_type"],"properties":{"deleted":{"type":"boolean"},"seats_released":{"type":"integer","minimum":0},"by_ticket_type":{"type":"array","items":{"type":"object","required":["ticket_tier_id","name","seats"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"seats":{"type":"integer","minimum":1}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to delete hold."}}}},"/v1/events/{eventId}/seats/{seatId}/history":{"get":{"tags":["catalog"],"summary":"Seat history","operationId":"getEventSeatHistory","description":"ENG-1723. Every release of one reserved seat, newest first (max 200): when, why, from and to state, the house hold it went to, the off-sale reason and note, and who did it (null for automatic releases).","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"seatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Seat history.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["history"],"properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/SeatHistoryEntry"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load seat history."}}}},"/v1/events/{eventId}/seats:replace-grid":{"post":{"tags":["catalog"],"summary":"Replace reserved-seat grid (upsert + delete available orphans)","description":"ENG-730. Upserts the desired seat rows (same geometry rules as seats:import), then deletes available seats not in the new set. Held/sold/blocked seats outside the set reject the whole operation. Requires confirm_remove_available=true when any available seats would be removed.","operationId":"replaceEventSeatsGrid","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","minItems":1,"maxItems":5000,"items":{"$ref":"#/components/schemas/SeatImportRow"}},"confirm_remove_available":{"type":"boolean","default":false,"description":"Required true when the replace would delete available seats."}}}}}},"responses":{"200":{"description":"Replace result counts.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatReplaceGridResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"confirm_remove_required — set confirm_remove_available true."},"422":{"description":"layout_not_reserved_seat, invalid_row, or seats_not_removable."}}}},"/v1/events/{eventId}/seats:import":{"post":{"tags":["catalog"],"summary":"Bulk-import seats for a reserved-seat event (idempotent)","operationId":"importEventSeats","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","minItems":1,"maxItems":5000,"items":{"$ref":"#/components/schemas/SeatImportRow"}}}}}}},"responses":{"200":{"description":"Import result counts.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatImportResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Event is not reserved_seat, or a row is malformed."}}}},"/v1/events/{eventId}/venue-house:apply":{"post":{"tags":["catalog"],"summary":"Apply the linked venue house to this event (ENG-720)","description":"Copies tenant venue house geometry into this event (copy, not a live link). reserved_seat uses seat import (never downgrades sold/held). section_and_type upserts sections only. Clears seating_ready. General admission events are rejected. Tenant is resolved from the API key or staff JWT, never from the body.","operationId":"applyEventVenueHouse","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Apply counts.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatImportResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"layout_not_seated, venue_required, house_empty, or related checklist reason."}}}},"/v1/events/{eventId}/venue-house:save":{"post":{"tags":["catalog"],"summary":"Save event house geometry to the linked venue (ENG-720)","description":"Writes this event's sections/seats into the linked venue house store (copy, not a live link). When venue.has_seating is already true, confirm_overwrite must be true. Tenant is resolved from the API key or staff JWT, never from the body.","operationId":"saveEventVenueHouse","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm_overwrite":{"type":"boolean"}},"example":{"confirm_overwrite":true}}}}},"responses":{"200":{"description":"Updated venue house.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/VenueHouse"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"overwrite_confirm_required, layout_not_seated, venue_required, or house_empty."}}}},"/v1/events/{eventId}/seating:ready":{"post":{"tags":["catalog"],"summary":"Mark or clear event seating_ready (ENG-720 / ENG-649)","description":"Seated layouts only. Marking ready requires inventory (reserved_seat: seats; section_and_type: sections). For reserved_seat, marking ready also syncs each ticket type inventory_total to the count of sellable seats on that type (blocked seats excluded). Clearing ready does not rewrite quantities. Publish/on_sale gates on seating_ready for those modes. General admission is rejected with layout_not_seated (hard floor). Tenant is resolved from the API key or staff JWT, never from the body.","operationId":"markEventSeatingReady","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ready"],"properties":{"ready":{"type":"boolean"}},"example":{"ready":true}}}}},"responses":{"200":{"description":"Updated seating_ready flag. inventory_sync lists tier totals changed from the seat map (reserved_seat mark-ready only).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"seating_ready":{"type":"boolean"},"inventory_sync":{"type":"array","items":{"type":"object","required":["ticket_tier_id","name","from","to"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"from":{"type":"integer"},"to":{"type":"integer"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"tier_not_active: on mark-ready, the seat map's staff-held chairs would create or grow a comp hold on an archived or turned-off ticket type. Nothing is written."},"422":{"description":"layout_not_seated, seating_inventory_required, seating_tiers_required, seating_location_required, seating_price_required, seating_price_unlinked (section_and_type mark-ready only), or inventory_below_committed."}}}},"/v1/events/{eventId}/sections":{"post":{"tags":["catalog"],"summary":"Create a section for an event","operationId":"createEventSection","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectionInput"}}}},"responses":{"201":{"description":"Section created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/sections/{sectionId}":{"patch":{"tags":["catalog"],"summary":"Update a section","operationId":"updateEventSection","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectionInput"}}}},"responses":{"200":{"description":"Section updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to update section."}}},"delete":{"tags":["catalog"],"summary":"Delete a section (cascades to its seats)","operationId":"deleteEventSection","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Section deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to delete section."}}}},"/v1/events":{"post":{"tags":["catalog"],"summary":"Create a draft event","operationId":"createEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EventInput"},{"type":"object","required":["title","starts_at"]}]}}}},"responses":{"201":{"description":"Event created (status draft).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-blocking notes: venue_geo_missing_distance_band_unavailable; pass_coverage_skipped (a new series show could not join one of its Every show / By day passes; the show saved)."},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"organizer_message_set_on_series: production_id names a series and organizer_message is set to something other than null or the series message; a program has no message of its own (guests see the series message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"A cross-field constraint (sales window, ends/starts, refund window) was violated. `seated_venue_required` when reserved_seat or section_and_type has no venue_id. `venue_not_found` when the place is missing. `pay_at_door_needs_stripe` (ENG-2255) when `cash_at_entry_enabled: true` would turn pay at the door on while the organizer's payment setup cannot take charges; the body carries `blocker` (`connect_required`, `connect_incomplete`, `connect_missing_on_platform` or `tenant_suspended`). Re-sending `true` on an event already set to pay at the door is not refused."},"500":{"description":"Internal error. `pay_at_door_check_failed` when the event's stored pay-at-door setting could not be read; nothing was saved."},"503":{"description":"payout_check_unavailable: `cash_at_entry_enabled: true` needs a payment-setup check and Stripe could not be reached; nothing was saved. Retry."}},"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"}],"description":"M46c dual-auth: API key `catalog:write` or staff JWT `event.write` + x-tenant-id."},"get":{"tags":["events"],"summary":"List events for the authenticated tenant","description":"M46c dual-auth: tenant API key with `catalog:read`, or staff JWT with `event.read` plus `x-tenant-id`. A tenant API key reads the buyer sale state, as on event detail and discovery: an on-sale event whose organizer's payment setup cannot take charges lists as `status: paused` with `sales_paused_reason`, and `status=on_sale` omits it. Staff JWT reads and filters the stored status.","operationId":"listEvents","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"$ref":"#/components/parameters/PreviousEditionFor"},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["events","limit","offset"],"properties":{"events":{"type":"array","items":{"type":"object","required":["id","tenant_id","title","status","starts_at","ends_at","sales_start_at","sales_end_at","ticketing_layout_mode","venue_id","category","hero_image_url","created_at","updated_at","production_id","timezone"],"properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"$ref":"#/components/schemas/EventStatus","description":"Tenant API key: the buyer sale state, as on event detail and discovery (`paused` when the organizer paused sales, or when AXYN did; see `sales_paused_reason`). Staff JWT: the stored status."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason","description":"Tenant API key only (always present there). Absent for staff JWT callers."},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"sales_start_at":{"type":["string","null"],"format":"date-time"},"sales_end_at":{"type":["string","null"],"format":"date-time"},"ticketing_layout_mode":{"$ref":"#/components/schemas/TicketingLayoutMode"},"venue_id":{"type":["string","null"],"format":"uuid"},"category":{"type":["string","null"],"enum":["music","food_and_drink","arts_and_theater","nightlife","festival","community","sports","other",null]},"hero_image_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"production_id":{"type":["string","null"],"format":"uuid"},"timezone":{"type":["string","null"]}},"additionalProperties":false}},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/v1/events/{eventId}":{"get":{"tags":["catalog"],"summary":"Event detail (API key: buyer EventDetail; staff JWT: admin Event row)","operationId":"getEventDetail","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key: buyer-flow id (source_venue_event_id) with event.id fallback. Staff JWT: event.id."}],"responses":{"200":{"description":"Event detail payload.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EventDetail"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load event."}}},"patch":{"tags":["catalog"],"summary":"Update an event (records material changes once published)","operationId":"updateEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EventInput"},{"type":"object","properties":{"entry_follows_series":{"type":"boolean","description":"Series show: true copies the series Entry & check-in defaults onto this show (and its ticket types that follow the show) and keeps them in step (400 not_in_series; 409 badge_pickup_locked_by_sales; not with entry_* in the same body). Sending entry_* or false unlinks; the show keeps its values. A show joining a series follows when its entry is still on the defaults."},"sales_follow_series":{"type":"boolean","description":"Series show: true copies the series sales_start_at onto this show and keeps it in step (not with sales_start_at in the same body). sales_end_at stays the show's own. Sending a different sales_start_at, or false, unlinks."},"excluded_from_passes":{"type":"boolean","description":"Series show: true takes it off Every show / By day passes for new buyers (holders keep it) and keeps it off; false lets it join again. 400 not_in_series on a standalone show."},"guest_visibility":{"type":"string","enum":["everyone","passes","no_one"],"description":"ENG-2344. Series program: who can see it. `passes` needs at least one chosen pass type (send `guest_visibility_pass_tier_ids`, or leave it out to keep the stored ones). Any other value clears the chosen pass types. 422 `program_visibility_not_in_series` for `passes` or `no_one` on an event outside a series; 422 `program_visibility_passes_required` for `passes` with none chosen. Leaving or changing series resets it to `everyone`. Saving sends no message to anyone and queues the search listing refresh."},"budget":{"$ref":"#/components/schemas/EventBudgetInput"},"previous_event_id":{"type":["string","null"],"format":"uuid","description":"ENG-2417. The event's previous edition (an earlier event of the same organization); null removes it. Send it alone: with any other field the update is refused whole (400 `previous_edition_alone`). Never set automatically and never copied by duplicate. Joining a series (`production_id` here, or POST /v1/productions/{productionId}/events) removes it and every other event's link to this one; every later save of a show in a series through this PATCH (other than a budget-only or previous-edition-only body) removes such links again, and leaving a series removes them first (ENG-2417 Q-A8). If removing them fails, the update still saves in full and the answer is 500 `previous_edition_clear_failed`: any such later save finishes it. If it fails while leaving a series, the show stays in the series and the answer is 500 `previous_edition_leave_clear_failed`. 422 with `message`: `previous_edition_self`, `previous_edition_loop` (\"That event comes after this one.\"), `previous_edition_draft`, `previous_edition_not_held` (it hasn't happened yet), `previous_edition_show_in_series` (a show inside a series; link the series), `previous_edition_not_found` (unknown or another organization's). A cancelled event is allowed."},"guest_visibility_pass_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"ENG-2344. Only with `guest_visibility: \"passes\"` (400 otherwise): the pass types whose holders see the program. Replaces the stored list. Each must be a pass type of the same series that opens this program, else 422 `program_visibility_pass_not_eligible`. A pass that opens the program and is left out is allowed: its holders get in and do not see it listed (read back as `guest_visibility_unlisted_passes`)."},"on_sale_with_series":{"type":"boolean","description":"Series program: false holds it as a draft when the series goes on sale, for a later announcement (400 not_in_series on a standalone event). It records the organizer's choice only; status still decides what guests see, and publishing runs the usual checks. Resets to true when the program leaves its series."},"announce_at":{"type":["string","null"],"format":"date-time","description":"Held series program (on_sale_with_series false): when the API publishes it, through the usual publish checks. Null means the organizer publishes it by hand. 400 announce_at_in_past for a new time that has passed; 409 announce_at_needs_hold when the program goes on sale with the series; 400 not_in_series. A program that is not ready at its time stays a draft with announce_failed_at set until the date changes."},"passes_before_announce":{"type":"boolean","description":"Held series program: false (the default) keeps the draft off Every show / By day passes until it is published, then it joins every pass, sold ones too. True adds it to passes now. 400 not_in_series."},"program_note":{"type":["string","null"],"maxLength":160,"description":"Legacy. The series page now shows the first line of the program's own About (description); this line only shows while the program has no About. Trimmed; empty clears it. 400 program_note_too_long."},"tax_follows_series":{"type":"boolean","description":"Series show: true copies the series tax onto this show and keeps it in step (400 not_in_series / series_tax_not_set; not with tax fields or production_id in the same body). false unlinks. Sending a tax different from the show's current one (tax_rate_bps, tax_not_applicable, or inherit_tax: true), or production_id, also unlinks; the same tax sent back (as a form autosave does) keeps the link. A new show created in a series with a tax set follows it unless it sends its own tax."},"pass_day_move":{"type":"string","enum":["keep","move"],"default":"keep","description":"A series show whose starts_at moves it to another calendar day: keep = it stays on the By day passes it opens now; move = it leaves By day passes for the day it left (new buyers only; holders keep it) and joins the new day's. Every show passes keep it either way."}}}]}}}},"responses":{"200":{"description":"Event updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-blocking notes: venue_geo_missing_distance_band_unavailable; pass_coverage_skipped (a series show that moved, got a place, or joined could not join one of its Every show / By day passes, e.g. a reserved-seat show whose pass already has holders; the show saved)."},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"series_setting_owned_by_series: the body changes a setting the event's series has set (waitlist_join_mode, walk_up_sales_enabled, cash_at_entry_*). Sending the series value back is accepted. organizer_message_set_on_series: the event is a program in a series and the body sets organizer_message; a program has no message of its own (guests see the series message). null, the value already stored, or the series message is accepted. badge_pickup_locked_by_sales and announce_at_needs_hold also answer 409.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"422":{"description":"A cross-field constraint was violated. ENG-2344: `program_visibility_not_in_series`, `program_visibility_passes_required` or `program_visibility_pass_not_eligible` (each also sent as `code`) when `guest_visibility` cannot be saved. `venue_not_found` when the place is missing. `layout_mode_locked` when `ticketing_layout_mode` changes after the event leaves draft. `seated_venue_required` when reserved_seat or section_and_type has no venue_id. On an event that is on_sale, paused or sold_out, a venue_id change must keep a venue with a street and city: `venue_required` (null or unknown venue), `venue_address_incomplete`, or `venue_lookup_failed`. `venue_required_for_tickets` when venue_id is cleared while the event has ticket types or a series pass admits it. `pay_at_door_needs_stripe` (ENG-2255) when `cash_at_entry_enabled: true` would turn pay at the door on while the organizer's payment setup cannot take charges; the body carries `blocker` (`connect_required`, `connect_incomplete`, `connect_missing_on_platform` or `tenant_suspended`). Re-sending `true` on an event already set to pay at the door is not refused."},"500":{"description":"Internal error. `pay_at_door_check_failed` when the event's stored pay-at-door setting could not be read; nothing was saved."},"503":{"description":"payout_check_unavailable: `cash_at_entry_enabled: true` needs a payment-setup check and Stripe could not be reached; nothing was saved. Retry."}},"description":"ENG-1662: a date inside a series does not set its own buyer refund policy. refunds_enabled / refund_policy / refund_window_hours are rejected with 400 while the event has a production_id; the series value is written through onto every date instead. ENG-2408: `budget` sets a standalone event's costs (EventBudgetInput); a body with only `budget` needs `event_budget.manage` instead of event write, so finance may send it. When sent, the response carries `data.budget` (EventBudgetRead). The staff read (GET) carries `budget` too, masked per C2; an API key read never does."},"delete":{"tags":["catalog"],"summary":"Delete a draft event","operationId":"deleteEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Event deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Event is not in draft status and cannot be deleted."}}}},"/v1/events/{eventId}/publish":{"post":{"tags":["catalog"],"summary":"Publish a draft event (draft → on_sale; idempotent)","operationId":"publishEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Event published (or already on sale).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Event is in a terminal/non-draft status and cannot be published."},"422":{"description":"Publish checklist failed. Typed error strings: venue_required, venue_address_incomplete, venue_lookup_failed (a program inside a series with no venue_id yet publishes as Venue TBD and skips these three; one that names a venue still needs its street and city), tax_config_required, seating_not_ready, seating_inventory_required, seating_tiers_required, payout_not_ready. seating_* apply only to reserved_seat and section_and_type; general is a hard floor (no seating gate). payout_not_ready includes blocker (connect_required, connect_incomplete, connect_missing_on_platform, tenant_suspended)."},"503":{"description":"payout_check_unavailable: Stripe Connect probe failed; publish fail-closes."}}}},"/v1/events/{eventId}/pause":{"post":{"tags":["catalog"],"summary":"Pause ticket sales for an on-sale event (idempotent when already paused)","operationId":"pauseEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Event paused (or already paused).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Event is not in a pausable status."}}}},"/v1/events/{eventId}/resume":{"post":{"tags":["catalog"],"summary":"Resume ticket sales for a paused event (paused → on_sale)","operationId":"resumeEvent","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Event resumed to on_sale.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Event is not paused and cannot be resumed."},"422":{"description":"Resume go-live checklist failed. venue_required, venue_address_incomplete or venue_lookup_failed when the event's venue has no street and city (fill it with PATCH /v1/tenants/{tenantId}/venues/{venueId}). Typed error payout_not_ready with blocker (connect_required, connect_incomplete, connect_missing_on_platform, tenant_suspended)."},"503":{"description":"payout_check_unavailable: Stripe Connect probe failed; resume fail-closes."}}}},"/v1/orders/preview-total":{"post":{"tags":["checkout"],"summary":"Preview an order total without reserving inventory (HF-001)","operationId":"previewOrderTotal","description":"Computes the exact amount a buyer will pay for a candidate cart (subtotal + platform fee + processing fee = total) without creating an order or reserving inventory. The previewed total equals the committed total. payment_method is optional (defaults to card; it only affects fee resolution).","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_id","venue_event_id","lines"],"properties":{"venue_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"lines":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/OrderLineInput"}},"coupon_codes":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":64},"description":"Optional coupon codes (each trimmed and uppercased server-side; max 5, distinct). More than one code requires every ticket tier in the cart to allow stacking (allow_multiple_coupons). Typed 400 error codes: coupon_not_found, coupon_inactive, coupon_not_started, coupon_exhausted, coupon_not_applicable, coupon_below_minimum_charge, coupon_duplicate, coupon_stacking_not_allowed. An expired code answers coupon_not_found, the same as an unknown code."}}}}}},"responses":{"200":{"description":"Computed total for the candidate cart.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OrderPreviewTotal"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"capacity_unavailable: not enough sellable inventory for the requested quantity (the same code order create uses). payout_not_ready: the organizer's payment setup cannot take charges (the same check order create runs, on every `payment_method`, `cash_at_entry` included since ENG-2255); refused here, before any card entry."},"422":{"description":"Cart is not priceable (e.g. tier not active or outside its sales window)."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/v1/events/{eventId}/custom-questions":{"get":{"tags":["catalog"],"summary":"List custom checkout questions for an event","operationId":"listEventCustomQuestions","security":[{"tenantApiKey":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Configured custom questions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/EventCustomQuestion"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["catalog"],"summary":"Replace custom checkout questions for an event","operationId":"replaceEventCustomQuestions","security":[{"tenantApiKey":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["questions"],"properties":{"questions":{"type":"array","maxItems":8,"items":{"type":"object","required":["prompt","answer_kind","is_required","grain","options"],"properties":{"prompt":{"type":"string","maxLength":500},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","acknowledgment"],"description":"`acknowledgment` is a box the guest must tick to agree to `prompt`: always saved required, with no options."},"is_required":{"type":"boolean"},"grain":{"type":"string","enum":["per_order","per_ticket"]},"options":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":120}}}}}}}}}}}},"responses":{"200":{"description":"Custom questions replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/orders":{"post":{"tags":["checkout"],"summary":"Create an order (reserve inventory)","operationId":"createOrder","description":"Reserves a multi-line cart (tickets + add-ons, optional reserved seats) and, for card-like methods, starts a Stripe PaymentIntent. Idempotent on (tenant, user, Idempotency-Key). A later create for the same buyer and event reuses a matching unpaid hold or cancels leftover holds before reserving again. Required disclosure: the checkout that collects this buyer's details must show `Ticketing by AXYN · Privacy`, with `Privacy` linking to `https://axyn.events/legal/privacy` (see Required disclosure in the API description). When the event requires attendee details (`attendee_details_mode` is `required`), send `attendees` and show this notice beside the fields that collect them: `Add an email to send someone their pass. Without one, the pass stays with you. The organizer sees these names and emails.`","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TenantIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_id","venue_event_id","payment_method","lines"],"properties":{"venue_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"lines":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/OrderLineInput"}},"seat_hold_owner":{"type":["string","null"],"format":"uuid","description":"Required when any line carries seat_id."},"purchaser_email":{"type":"string"},"purchaser_name":{"type":"string"},"purchaser_phone":{"type":"string"},"sms_consent":{"type":["object","null"],"description":"ENG-2871: the text boxes the guest ticked under the phone field. Send only when the event's sms_consent is non-null, with its wording_version. Neither box is needed to buy. A ticked box needs purchaser_phone in E.164 (400 `purchaser_phone is required to receive texts` / `purchaser_phone needs a country code to receive texts`); a box on an event without the offer is 400 `sms_consent is not offered for this event`; an old wording_version is 400 `sms_consent wording_version is out of date` (re-read the event). The boxes become consent when the order is paid.","properties":{"event_updates":{"type":"boolean","description":"The event updates box (EventDetail.sms_consent.event_updates_label)."},"marketing":{"type":"boolean","description":"The news and offers box (EventDetail.sms_consent.marketing_label)."},"wording_version":{"type":"string","description":"EventDetail.sms_consent.wording_version, as shown to the guest."}},"additionalProperties":false},"funnel_session_key":{"type":"string","minLength":8,"maxLength":128,"description":"ENG-2312: the funnel journey this order came from (the Web SDK sends it; with the commerce pixel read it with axyn('getSession', cb)). Kept only when the organizer has funnel analytics on and AXYN recorded that journey for this event or series. An order is never refused or delayed because of it: a missing, malformed or unknown value is ignored."},"postal_code":{"type":"string","maxLength":32,"description":"Required purchaser postal code. Country is inferred when unambiguous."},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code; required when postal code is ambiguous."},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"address_line1":{"type":"string","maxLength":200,"description":"Required when the event address_collection_mode is full."},"address_line2":{"type":"string","maxLength":200},"section_id":{"type":"string"},"ticket_type_id":{"type":"string"},"ticket_type_label":{"type":"string"},"section_name":{"type":"string"},"displayed_total_cents":{"type":"integer"},"coupon_codes":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":64},"description":"Optional coupon codes (each trimmed and uppercased server-side; max 5, distinct). More than one code requires every ticket tier in the cart to allow stacking (allow_multiple_coupons). Typed 400 error codes: coupon_not_found, coupon_inactive, coupon_not_started, coupon_exhausted, coupon_not_applicable, coupon_below_minimum_charge, coupon_duplicate, coupon_stacking_not_allowed. An expired code answers coupon_not_found, the same as an unknown code. Each coupon row is re-validated and its redemption counter incremented atomically inside the order transaction."},"custom_answers":{"type":"array","description":"Typed answers for the event's configured custom questions. An `acknowledgment` question takes only `yes_no: true`, sent after the guest ticked an unticked box showing the full `prompt`; never pre-tick it. Anything else, or no answer, is refused 400 `acknowledgment_not_agreed` with that `question_id`. The wording answered is stored with the answer. ENG-3338: a question with `ticket_tier_ids` is asked only for cart tickets of those types (`ticket_ordinal` numbers every ticket in the cart, in line order); a required one needs an answer for each of them, and an answer for any other ticket, or a `per_order` answer when no cart ticket is one of them, is refused 400 `custom_answer_not_applicable` with that `question_id`.","items":{"type":"object","required":["question_id"],"properties":{"question_id":{"type":"string","format":"uuid"},"ticket_ordinal":{"type":"integer","minimum":1},"text":{"type":"string","maxLength":500},"yes_no":{"type":"boolean"},"option_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendeeInput"},"description":"ENG-733. Who each ticket is for. Send one entry per ticket that requires details. A ticket requires details when its show's effective `attendee_details_mode` is `required`. A series pass type follows the series value. Entries for the same ticket type are matched in array order. A reserved-seat ticket is matched by `seat_id`. Add-on lines never take attendees. If nothing in the order requires details, this field is ignored and not stored. `ticket_tier_id` and `seat_id` are matched case-insensitively. On an idempotent replay the entries are checked against the tickets the stored order holds. A ticket named with an email is issued to that person, who gets their own pass email with no amounts. A ticket named without an email stays with the buyer under that person's name. The buyer's confirmation email always holds every pass of the order, so `purchaser_email` is required when tickets name attendees. Typed 400 error codes: attendee_details_required, attendee_details_invalid, purchaser_email_required_for_attendees. Typed 500 error codes: attendee_details_check_failed (no order was created; the same request can be retried; answered as 503 with Retry-After when the database is busy), attendee_details_store_failed (the order is cancelled before any payment starts; retry with a new Idempotency-Key)."}}}}}},"responses":{"200":{"description":"Idempotent replay of an existing order, or a reused unpaid hold. Same envelope as 201.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"},"payment":{"$ref":"#/components/schemas/PaymentView"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicket"}},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendee"},"description":"ENG-733. The attendees the buyer entered for this order. Empty when the order collected none. Returned only to the buyer who owns the order."}}}}}}}},"201":{"description":"Order created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"},"payment":{"$ref":"#/components/schemas/PaymentView"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicket"}},"cash_arrangement":{"allOf":[{"$ref":"#/components/schemas/CashAtEntryArrangement"}],"description":"Present only for a cash-at-entry order (D6.9): the order is parked in awaiting_cash with the amount the door collects."},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendee"},"description":"ENG-733. The attendees the buyer entered for this order. Empty when the order collected none. Returned only to the buyer who owns the order."}}}}}}}},"400":{"description":"Validation error. ENG-733: `attendee_details_required` and `attendee_details_invalid` carry `message` and `details` (AttendeeDetailsError). No inventory is reserved. `purchaser_email_required_for_attendees` (ApiError with a buyer `message`): the order names attendees and no purchaser email was sent or held on the session.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiError"},{"$ref":"#/components/schemas/AttendeeDetailsError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"State conflict: sold_out, capacity_unavailable, addon_sold_out, or payout_not_ready (Connect not ready to sell, on every payment method including cash_at_entry since ENG-2255; no inventory reserved)."},"422":{"description":"Cash at Entry is not enabled for this event (default OFF).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."},"502":{"$ref":"#/components/responses/PaymentGatewayError"},"503":{"description":"payout_check_unavailable: Stripe Connect probe failed; checkout fail-closes without reserving inventory. Or, with `Retry-After`, the database is busy: a step could not get a connection in time and never ran. Send the same request again after `Retry-After` seconds with the same Idempotency-Key, so the retry replays any order already made. The `error` code is the one that step answers with otherwise.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only when the database is busy.","schema":{"type":"integer","minimum":0}}}}}}},"/v1/orders/allocation":{"post":{"tags":["checkout"],"summary":"Reserve from a paid partner allocation (private link)","operationId":"createAllocationOrder","description":"ENG-1565 — reserves units from a named GA hold using the allocation token from a private link. The link is an extra gate in front of the ordinary checkout, never a substitute for one: the buyer still authenticates (guest sessions included), the tenant is resolved from venue_event_id and never from the token, and the order that comes out is the ordinary order with the ordinary timer, price, payment, ticket and scanner behaviour. Idempotent on (tenant, user, Idempotency-Key). Every way the token can fail — expired, rotated, released, exhausted, wrong tenant, wrong tier, or never valid — collapses to one allocation_unavailable 404 so the endpoint cannot be used to map another organizer’s inventory.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","allocation_token","quantity","payment_method"],"properties":{"venue_event_id":{"type":"string","format":"uuid","description":"Event being checked out. The tenant is resolved from this, never from the token."},"allocation_token":{"type":"string","minLength":32,"maxLength":128,"pattern":"^[A-Za-z0-9_-]{32,128}$","description":"Raw bearer from the private link. Shown once at create or rotate and not recoverable afterwards."},"quantity":{"type":"integer","minimum":1,"maximum":50},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendeeInput"},"description":"ENG-733. Who each ticket is for. Required when the event's effective `attendee_details_mode` is `required`: send one entry per unit in `quantity`, each with the `ticket_tier_id` the allocation draws from. Same rules, limits and error codes as `attendees` on POST /v1/orders. Ignored and not stored when the event does not require details."},"purchaser_email":{"type":"string","description":"Used only when the authenticated session carries no verified email."},"purchaser_name":{"type":"string"},"purchaser_phone":{"type":"string","description":"Stored in E.164 when it reads as one: typed with its + and country code, or a US / CA number with `country` US or CA. Otherwise stored exactly as typed, and the order still goes through. The event's country is never assumed."},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country the buyer states, as on POST /v1/orders. Used only to read a purchaser_phone typed without its +."}}}}}},"responses":{"200":{"description":"Idempotent replay of an order already created for this key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/TicketOrderStatus"},"total_cents":{"type":"integer"},"currency":{"type":"string"},"reservation_expires_at":{"type":["string","null"],"format":"date-time","description":"When the unpaid hold lapses. Same timer as an ordinary order."}}},"quantity":{"type":"integer"},"ticket_tier_id":{"type":"string","format":"uuid","description":"The tier the allocation draws from; chosen by the pool, not the caller."}}}}}}}},"201":{"description":"Units reserved from the allocation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/TicketOrderStatus"},"total_cents":{"type":"integer"},"currency":{"type":"string"},"reservation_expires_at":{"type":["string","null"],"format":"date-time","description":"When the unpaid hold lapses. Same timer as an ordinary order."}}},"quantity":{"type":"integer"},"ticket_tier_id":{"type":"string","format":"uuid","description":"The tier the allocation draws from; chosen by the pool, not the caller."}}}}}}}},"400":{"description":"Validation error. ENG-733: `attendee_details_required` and `attendee_details_invalid` carry `message` and `details` (AttendeeDetailsError). `purchaser_email_required_for_attendees` (ApiError with a buyer `message`): attendees were named and no purchaser email was sent or held on the session. No inventory is reserved.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiError"},{"$ref":"#/components/schemas/AttendeeDetailsError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"allocation_unavailable: the token is expired, rotated, released, exhausted, for another tenant or another event, or was never valid. Deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"insufficient_allocation_remaining: the pool is live but holds fewer units than requested (distinguished from 404 only because the buyer can act on it by asking for fewer); or idempotency_key_reused: the Idempotency-Key already names another order for this buyer, or another buyer's reservation on this pool. Retry with a fresh key. Or tier_not_active: the pool's ticket type was archived or turned off; the pool keeps its units but sells none until the type is on again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"invalid_venue_event_id, invalid_quantity, or invalid_payment_method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/orders/{orderId}/payments/start":{"post":{"tags":["checkout"],"summary":"Start or resume payment for an order","description":"Returns the Stripe client secret for the order's PaymentIntent. Required disclosure: the card step must show `Ticketing by AXYN · Privacy`, with `Privacy` linking to `https://axyn.events/legal/privacy` (see Required disclosure in the API description).","operationId":"startOrderPayment","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Payment started/resumed, or order already paid.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"},"payment":{"$ref":"#/components/schemas/PaymentView"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicket"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"payout_not_ready: live tenant has no connected Stripe account (or Connect is incomplete). No new PaymentIntent is created. In-flight platform PaymentIntents can still be resumed."},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/PaymentStartGatewayError"},"503":{"description":"payout_check_unavailable: Stripe Connect probe failed; payment start fail-closes."}}}},"/v1/orders/{orderId}/verify-payment":{"post":{"tags":["checkout"],"summary":"Synchronously verify an order's payment (HF-017)","operationId":"verifyOrderPayment","description":"Returns a definitive paid/failed/pending status by reading Stripe live (paymentIntents.retrieve), reconciling it with the order, and never showing \"pending forever\". The success page calls this on return from Stripe and may poll it ~1/s up to 30s while a charge settles; the webhook reconciles thereafter. Idempotent on payment_intent_id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Definitive verification result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PaymentVerification"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Order has no Stripe payment to verify (e.g. cash-at-entry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Payment provider unreachable; safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/orders/{orderId}/cash-arrangement":{"get":{"tags":["checkout"],"summary":"Get an order's cash-at-entry pre-arrangement (D6.9)","operationId":"getOrderCashArrangement","description":"Returns the cash-at-entry pre-arrangement (amount the door collects + status) for a cash order. Owner or venue staff only. 404 for a non-cash order.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cash-at-entry arrangement.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CashAtEntryArrangement"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Internal error."}}}},"/v1/orders/{orderId}/confirmation-bearers":{"post":{"tags":["checkout","tickets"],"summary":"Mint fresh purchaser confirmation bearers","operationId":"mintOrderConfirmationBearers","description":"ENG-468 — returns fresh raw ticket-url bearer tokens for the purchaser's paid order cohort. Intended for hosted confirmation sessionStorage only; never put these in the confirmation URL. ENG-3387: also returns `passes`, each of the buyer's passes with its Live Pass link. Only the order's buyer may call it (403 otherwise), and only for a paid order (409 `order not paid`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"string"},"description":"Raw ticket-url bearer tokens for confirmation sessionStorage."},"passes":{"type":"array","description":"ENG-3387: each of the buyer's passes with its Live Pass link, the same `/p/{share_code}` link the purchase email sends, whether this call comes before or after that email. Reading it never creates a new link or cancels the emailed one. A pass is left out when it is no longer the buyer's: transferred to and accepted by someone else (unless it came back to the buyer's own email), or voided, refunded, cancelled or redeemed. A pass named for a guest at checkout is still listed (ENG-733). A pass with no live link yet is also left out; call again to pick it up.","items":{"type":"object","required":["ticket_id","live_pass_url"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"live_pass_url":{"type":"string","format":"uri","description":"The pass's Live Pass link (`/p/{share_code}`). Opens the pass for whoever holds it; show it only to the buyer."}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."},"502":{"description":"Bearer mint failure"}}}},"/v1/orders/{orderId}/extend-hold":{"post":{"tags":["checkout"],"summary":"Extend an unpaid checkout hold","operationId":"extendCheckoutHold","description":"WCAG 2.2.1 warn-and-extend for ENG-1577. Explicit buyer action bumps reservation_expires_at and expires_at by one current hold window (900s) and increments hold_extension_count, capped at 10. Does not re-acquire inventory; sold-out after the original hold still extends. Expired, paid, or cap-exhausted holds return 409.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Hold extended by one window.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/orders/{orderId}/cancel":{"post":{"tags":["checkout"],"summary":"Cancel an unpaid checkout hold","operationId":"cancelReservedOrder","description":"Releases a buyer-owned reserved or pending_payment order so a refresh or abandon cannot stack inventory holds. Already cancelled or expired orders return 200. Paid and other terminal statuses return 409.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Hold cancelled, or already cancelled/expired.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/orders/{orderId}":{"get":{"tags":["checkout"],"summary":"Get an order with its tickets","operationId":"getOrder","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order and tickets.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/TicketOrder"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicket"}},"tenant":{"oneOf":[{"$ref":"#/components/schemas/BuyerTenantBrand"},{"type":"null"}]},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/OrderDiscount"},"description":"ENG-1888: one line per applied discount."},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/OrderAttendee"},"description":"ENG-733. The attendees the buyer entered for this order. Empty when the order collected none. Returned only to the buyer who owns the order."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Internal error."}}}},"/v1/seats/hold":{"post":{"tags":["seats"],"summary":"Hold reserved seats (TTL)","operationId":"holdSeats","description":"All-or-nothing hold; idempotent re-hold by the same owner. Owner is typically the cart/order id. With a catalog:read API key the hold runs for the seats' organizer: the key tenant's own seats, or seats of ONE public (on_sale or sold_out) event of another organizer (the seat map that key can read). Seats spread over organizers or events, seats of a draft or cancelled event, and sandbox organizers on the hosted buyer surface return 404 seat_not_found.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hold_owner","seat_ids"],"properties":{"hold_owner":{"type":"string","format":"uuid"},"seat_ids":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"ttl_seconds":{"type":"integer","minimum":30,"maximum":1800,"default":900},"accessible_intent":{"type":"boolean","description":"Required to hold an accessible seat (ENG-1131). Missing → 422 accessible_intent_required."},"restricted_ack":{"type":"boolean","description":"Required to hold a restricted seat. Missing → 422 restricted_ack_required."},"access_code":{"type":"string","description":"Unlocks a named house hold at the listed price. Wrong code → 422 invalid_access_code with no hold name."}}}}}},"responses":{"200":{"description":"Seats held.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"seats":{"type":"array","items":{"$ref":"#/components/schemas/Seat"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"State conflict: a seat is no longer available, or payout_not_ready (the seats' organizer cannot take charges, so sales are paused whatever the event takes, pay at the door included; event detail reads `status: paused`). Refused before any card entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Hold refused: accessible_intent_required, restricted_ack_required, house_hold_locked, invalid_access_code, or orphan_seat (a leftover single available chair in the row)."},"429":{"description":"rate limit exceeded: more than 60 hold requests a minute from this buyer session, or 120 from this IP address. seat_hold_limit_exceeded: the hold would leave this IP address holding more than 40 chairs of the event at once, across every session and hold_owner (released, expired and sold chairs stop counting).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/seats/release":{"post":{"tags":["seats"],"summary":"Release held seats","operationId":"releaseSeats","description":"Releases seats held by hold_owner. Organizer resolution is the same as POST /v1/seats/hold.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hold_owner","seat_ids"],"properties":{"hold_owner":{"type":"string","format":"uuid"},"seat_ids":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"Seats released (count).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"released":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me/tickets":{"get":{"tags":["tickets"],"summary":"List the authenticated user's tickets","operationId":"listMyTickets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Tickets owned by or assigned to the caller.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"series":{"description":"ENG-2337. The series the ticket's program belongs to. Null for a standalone event. For a pass, and when `lineup_on_live_pass` is false, `event.title` is the series title and `event.description` / `event.hero_image_url` are null.","oneOf":[{"$ref":"#/components/schemas/HeldTicketSeries"},{"type":"null"}]},"pass":{"description":"ENG-2338. Only when the ticket's type is a pass. `event` start, end and venue are its host program's and are not the pass's own.","oneOf":[{"$ref":"#/components/schemas/HeldTicketPass"},{"type":"null"}]}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Internal error."}}}},"/v1/tickets/scanner-tokens":{"post":{"tags":["scanning"],"summary":"Issue a scanner device token","operationId":"createScannerToken","description":"Huddle staff JWT (organizer admin, event manager, or door lead) plus x-tenant-id. Hired scanners and walk-up sales receive 403. Returns the one-time token value once.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","venue_id"],"properties":{"venue_event_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"label":{"type":["string","null"]},"expires_in_minutes":{"type":"integer","minimum":5,"maximum":1440,"default":240}}}}}},"responses":{"201":{"description":"Token issued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"token":{"type":"string"},"token_prefix":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"label":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Internal error."}}},"get":{"tags":["scanning"],"summary":"List scanner tokens for an event","operationId":"listScannerTokens","security":[{"bearerAuth":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_revoked","in":"query","required":false,"schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"Tokens.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"tokens":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tickets/scanner-tokens/{tokenId}/revoke":{"post":{"tags":["scanning"],"summary":"Revoke a scanner token","operationId":"revokeScannerToken","security":[{"bearerAuth":[]}],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Revoked (idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revoked_at":{"type":"string","format":"date-time"},"already_revoked":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/scanner-join-codes":{"get":{"tags":["scanning"],"summary":"Get or mint the active event scanner join code","operationId":"getScannerJoinCode","description":"Huddle staff JWT (organizer admin, event manager, or door lead) plus x-tenant-id. Hired scanners and walk-up sales receive 403. Returns the one active 6-digit door join code for the event, minting it if missing. Unique per event, not per scanner. Share the digits outdoors (glare) and the QR indoors.","security":[{"bearerAuth":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Active join code.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"code":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"event_title":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"join_qr_payload":{"type":"string"},"join_qr_png_data_url":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tickets/scanner-join-codes/rotate":{"post":{"tags":["scanning"],"summary":"Rotate the event scanner join code","operationId":"rotateScannerJoinCode","description":"Huddle staff JWT (organizer admin, event manager, or door lead) plus x-tenant-id. Hired scanners and walk-up sales receive 403. Revokes the current 6-digit code and mints a new one. Existing scn_ device tokens stay valid until expiry or revoke.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id"],"properties":{"event_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"New join code.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"code":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"event_title":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"join_qr_payload":{"type":"string"},"join_qr_png_data_url":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tickets/scanner-join-codes/redeem":{"post":{"tags":["scanning"],"summary":"Redeem a 6-digit scanner join code","operationId":"redeemScannerJoinCode","description":"Public. Tenant and event come from the join-code row, never from the body. Possession of the 6-digit PIN mints a unique scn_ device token. Guessing is capped by a Postgres-backed per-IP budget shared across API replicas (10 attempts per minute and 30 per 15 minutes) plus a per-process limiter at the same ceiling. Each active code mints at most 40 devices. Rotate after the night; rotate does not revoke already-minted tokens.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"join_payload":{"type":"string"}}}}}},"responses":{"201":{"description":"Device token minted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"token":{"type":"string"},"token_prefix":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"venue_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"event_title":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"join_payload":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"This join code has minted the maximum number of device tokens. Rotate the code."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Shared per-IP guess budget exceeded (10/min, 30/15min). Retry later."}}}},"/v1/tickets/scanner-tokens/me":{"get":{"tags":["scanning"],"summary":"Read this device token's name and assigned lane","operationId":"getScannerTokenMe","description":"Volunteer path. Auth is x-scanner-token. Returns label plus organizer-assigned lane so the device can adopt the huddle assignment without a second setup. Rate-limited to 40 calls per token per minute (door poll is every 5s).","security":[{"scannerToken":[]}],"parameters":[{"name":"x-scanner-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current token view.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"label":{"type":["string","null"]},"assigned_lane_id":{"type":["string","null"]},"event_id":{"type":"string","format":"uuid"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"Rate limit exceeded (40/min per scanner token)."}}},"patch":{"tags":["scanning"],"summary":"Set the scanner display name on this device token","operationId":"patchScannerTokenMe","description":"Volunteer path after join. Auth is x-scanner-token. Writes first + last name onto scanner_tokens.label.","security":[{"scannerToken":[]}],"parameters":[{"name":"x-scanner-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Label saved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"label":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"Rate limit exceeded (40/min per scanner token)."}}}},"/v1/tickets/scanner-roster":{"get":{"tags":["scanning"],"summary":"List joined scanners for an event","operationId":"getScannerRoster","description":"Staff JWT plus `x-tenant-id` (or a partner API key). Roster of active scanner tokens (join-code devices and staff-minted tokens) with display names and organizer-assigned lanes. Tenant comes from the API key or `x-tenant-id`, not the JWT and not the body. ACL is the caller's `tenant_staff` scan grant.","security":[{"bearerAuth":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Roster.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"scanners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"token_prefix":{"type":"string"},"label":{"type":["string","null"]},"assigned_lane_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["active","expired"]}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tickets/scanner-tokens/{tokenId}/lane":{"patch":{"tags":["scanning"],"summary":"Assign or clear a joined scanner's lane","operationId":"patchScannerTokenLane","description":"Staff JWT. Organizer override wins: assigning a lane clears that lane on other active tokens for the same event. Pass lane_id null to unassign. Lane ids are event-owned strings; an empty catalog leaves scanners unbound.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lane_id"],"properties":{"lane_id":{"type":["string","null"],"maxLength":64}}}}}},"responses":{"200":{"description":"Lane saved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"scanner":{"type":"object"},"cleared_token_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Token expired or unique lane constraint lost a race."}}}},"/v1/door-stations":{"get":{"tags":["scanning"],"summary":"List the door station catalog for an event","operationId":"listDoorStations","description":"Staff JWT with door access to the event. Returns the event-owned lanes (stations) in organizer order, each with the ticket tiers it admits. lane_id is the key carried by scanner_tokens.assigned_lane_id and scanner_devices.lane_id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Native event.id or the opaque source_venue_event_id."}],"responses":{"200":{"description":"Door station catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"stations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"lane_id":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":120},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ticket tiers this station admits. Empty when admits_all_tiers is true."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["scanning"],"summary":"Add a door station to the event catalog","operationId":"createDoorStation","description":"Staff JWT with door.station.manage on the event. lane_id is the immutable key doors bind to; name is the organizer label. Omitting admits_all_tiers infers it from admit_tier_ids (named tiers narrow the station, none admits everything). A station that admits nothing is rejected.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id","lane_id"],"properties":{"event_id":{"type":"string","format":"uuid"},"lane_id":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":120},"sort_order":{"type":"integer","minimum":0,"maximum":10000},"is_active":{"type":"boolean","default":true},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","maxItems":200,"items":{"type":"string","format":"uuid"},"description":"Tiers this station admits. Must be tiers on the same event. Replaces the stored set wholesale."}}}}}},"responses":{"201":{"description":"Door station created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"lane_id":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":120},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ticket tiers this station admits. Empty when admits_all_tiers is true."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"door_station_lane_exists: that lane_id is already in this event catalog."}}}},"/v1/door-stations/me":{"get":{"tags":["scanning"],"summary":"The door station this scanner token is standing at","operationId":"getScannerDoorStation","description":"Scanner device token. Tenant and event come from the live scn_ row, never x-tenant-id. station is null when the token has no lane assigned or its lane is not in the catalog.","security":[{"scannerToken":[]}],"responses":{"200":{"description":"Assigned station, or null when unbound.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"assigned_lane_id":{"type":["string","null"],"maxLength":64},"station":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"lane_id":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":120},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ticket tiers this station admits. Empty when admits_all_tiers is true."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},{"type":"null"}]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/door-stations/{stationId}":{"patch":{"tags":["scanning"],"summary":"Rename a door station or change what it admits","operationId":"patchDoorStation","description":"Staff JWT with door.station.manage on the station’s event. lane_id is immutable — renaming the key would unbind every door standing there. admit_tier_ids replaces the stored set wholesale, and setting admits_all_tiers true on its own clears it; the merged state must still admit something, and a widening that also names tiers is rejected.","security":[{"bearerAuth":[]}],"parameters":[{"name":"stationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"sort_order":{"type":"integer","minimum":0,"maximum":10000},"is_active":{"type":"boolean"},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","maxItems":200,"items":{"type":"string","format":"uuid"},"description":"Tiers this station admits. Must be tiers on the same event. Replaces the stored set wholesale."}}}}}},"responses":{"200":{"description":"Door station saved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"lane_id":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":120},"sort_order":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"admits_all_tiers":{"type":"boolean"},"admit_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ticket tiers this station admits. Empty when admits_all_tiers is true."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["scanning"],"summary":"Remove a door station from the catalog","operationId":"deleteDoorStation","description":"Staff JWT with door.station.manage on the station’s event. Fails closed with 409 while a live scanner token or an active registered device still carries that lane — deactivate (is_active false) is the in-event move.","security":[{"bearerAuth":[]}],"parameters":[{"name":"stationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Door station removed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"door_station_lane_in_use: a live scanner token or active device still binds this lane."}}}},"/v1/tickets/scan":{"post":{"tags":["scanning"],"summary":"Staff online scan","operationId":"staffScan","description":"Staff/admin only. Business outcome returned in data.result_code with HTTP 200. When client_device_id names a device registered to a door station that does not admit the ticket's tier, the outcome is wrong_door and the ticket is left unused.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_code"],"properties":{"qr_code":{"type":"string"},"client_device_id":{"type":"string","maxLength":128}}}}}},"responses":{"200":{"description":"Scan processed (see result_code).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"Scan view including result_code, result_message, ticket/event fields, scanned_at, is_offline=false."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/scanner/manual-lookup":{"post":{"tags":["scanning"],"summary":"Manual ticket lookup (HF-023)","operationId":"scannerManualLookup","description":"Door staff find a ticket by typed buyer identifier (name / email / order id / order reference / ticket number) when a QR cannot be read. Scoped to one event; returns masked buyer info only. ENG-1603: also returns advance pay-at-door orders still awaiting cash (no tickets exist until the door collects) as pending_cash_orders. A cash-desk-only grant (cash_collector) receives pending_cash_orders and an empty matches.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","query"],"properties":{"venue_event_id":{"type":"string","format":"uuid"},"query":{"type":"string","minLength":2,"maxLength":120},"search_fields":{"type":"array","items":{"type":"string","enum":["name","email","order_id","order_reference","ticket_number"]}}}}}}},"responses":{"200":{"description":"Lookup matches.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/ScannerManualLookupMatch"}},"pending_cash_orders":{"type":"array","items":{"$ref":"#/components/schemas/ScannerPendingCashOrder"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/scanner/manual-admit":{"post":{"tags":["scanning"],"summary":"Manual admit override (HF-023/HF-026)","operationId":"scannerManualAdmit","description":"Door staff admit a ticket verified via manual lookup (QR unreadable). Always written to the append-only scan audit with is_manual_admit=true and the override reason. Business outcome in data.result_code (HTTP 200).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","ticket_id"],"properties":{"venue_event_id":{"type":"string","format":"uuid"},"ticket_id":{"type":"string","format":"uuid"},"override_reason":{"type":"string","maxLength":500},"client_device_id":{"type":"string","maxLength":128}}}}}},"responses":{"200":{"description":"Manual admit processed (see result_code).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"Admit view including result_code, result_message, ticket/event fields, re_entry_policy, admit_action (entry, re_entry or exit), entry_count, is_manual_admit=true, scanned_at. ENG-1920: a manual admit re-admits under the admitted ticket's re-entry setting exactly as a scan does."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Manual admit could not be completed."}}}},"/v1/scanner/pickup":{"post":{"tags":["scanning"],"summary":"Record badge handoff (ENG-1563)","operationId":"scannerRecordBadgePickup","description":"Staff with door.pickup record that a physical badge was handed over for one live badge pickup ticket. Idempotent on idempotency_key; one success per ticket across desks. Never remints the Live Pass. When the ticket was sold with pickup_requires_scan false, the handoff also checks the guest in through the audited manual-admit path (override reason \"Badge pickup counts as entry\"). The desk hours are the entry window, so an early pickup still checks the guest in; if the door refuses (refunded, voided, unpaid), nothing is handed over. id_checked is an attestation only; no ID data is stored.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","ticket_id","idempotency_key"],"properties":{"venue_event_id":{"type":"string","format":"uuid","description":"The desk's event. Tickets from other events (unless a pass covers this event) return ticket_not_found."},"ticket_id":{"type":"string","format":"uuid"},"idempotency_key":{"type":"string","minLength":1},"id_checked":{"type":"boolean","description":"Staff attest they checked photo ID. Required when the ticket snapshot requires an ID check."},"note":{"type":["string","null"],"maxLength":500}}}}}},"responses":{"200":{"description":"Badge handed over (or an idempotent replay).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string","enum":["ok"]},"already_completed":{"type":"boolean"},"picked_up_at":{"type":"string","format":"date-time"},"actor_staff_user_id":{"type":"string","format":"uuid"},"checked_in":{"type":"boolean","description":"True when this type's pickup checks the guest in (pickup_requires_scan false)."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"ticket_not_found (unknown, wrong event, or wrong tenant; same shape for all)."},"409":{"description":"Business refusal in error: pickup_not_available, pickup_already_completed, pickup_window_closed, pickup_id_check_required, idempotency_key_reused (key already used for a different ticket), or pickup_admit_refused with admit_result_code (pickup counts as entry and the door refused, e.g. not_yet_valid or revoked)."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"pickup_failed"}}}},"/v1/scanner/devices/register":{"post":{"tags":["scanning"],"summary":"Register a scanning device (T-077 Path B)","operationId":"scannerRegisterDevice","description":"Register a device against an event so it can scan when the event requires device registration. Idempotent on (event, device_id): re-registering refreshes lane/label and clears any prior revocation. On an event that has a wristband key a revoked registration is never cleared: the answer is 403 `device_revoked`.\n\nWristband key (optional `band_key` field, attested Android scanners only). Send `{ \"step\": \"challenge\" }` to register and receive a one-time challenge (valid 5 minutes). Generate an RSA key (2048 bits or more) with purpose WRAP_KEY only (a key that also has DECRYPT, SIGN or any other purpose is refused) in the phone's secure hardware using that challenge as the attestation challenge, then send `{ \"step\": \"deliver\", \"attestation_chain\": [...] }` with the key's certificate chain. The answer carries the event key as an Android `SecureKeyWrapper` that only that phone's hardware can import; the imported key can only AES-encrypt and expires at `expires_at`. Every delivery needs a new challenge and a new attestation.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","client_device_id"],"properties":{"venue_event_id":{"type":"string","format":"uuid"},"client_device_id":{"type":"string","maxLength":128},"lane_id":{"type":"string","maxLength":64},"label":{"type":"string","maxLength":120},"band_key":{"$ref":"#/components/schemas/BandKeyRequest"}}}}}},"responses":{"201":{"description":"Device registered. With `band_key` in the request, `data.band_key` carries the challenge or the wrapped key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"allOf":[{"$ref":"#/components/schemas/ScannerDevice"},{"type":"object","properties":{"band_key":{"oneOf":[{"$ref":"#/components/schemas/BandKeyChallenge"},{"$ref":"#/components/schemas/BandKeyDelivery"}]}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Not allowed. `scanner_not_authorized`: no door grant for this event. `device_revoked`: this phone's registration was revoked (events with a wristband key). `band_key_not_eligible`: this phone or app may not hold the key (iPhone, no hardware attestation, unlocked or unverified boot, revoked attestation key, wrong app). `attestation_invalid`: the attestation is malformed, or its challenge is unknown, already used or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["scanner_not_authorized","device_revoked","band_key_not_eligible","attestation_invalid"]}}}}}},"404":{"description":"`event_not_found`: no such event for this organizer. `band_key_not_found`: `band_key` was sent for an event that has no wristband key; nothing is registered or changed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["event_not_found","band_key_not_found"]}}}}}},"410":{"description":"`band_key_destroyed`: the event's wristband key was destroyed (30 days after the event ended).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["band_key_destroyed"]}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Device registration could not be completed."},"503":{"description":"`band_key_temporarily_unavailable`: the wristband key cannot be delivered right now. Try again; ticket scanning is unaffected.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["band_key_temporarily_unavailable"]}}}}}}}}},"/v1/scanner/devices":{"get":{"tags":["scanning"],"summary":"List registered scanning devices (T-077 Path B)","operationId":"scannerListDevices","description":"List devices registered for an event. Active only by default; pass include_revoked=true for the full registration audit.","security":[{"bearerAuth":[]}],"parameters":[{"name":"venue_event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Registered devices.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer"},"devices":{"type":"array","items":{"$ref":"#/components/schemas/ScannerDevice"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"502":{"description":"Device list could not be retrieved."}}}},"/v1/scanner/devices/{registrationId}/revoke":{"post":{"tags":["scanning"],"summary":"Revoke a scanning device registration (T-077 Path B)","operationId":"scannerRevokeDevice","description":"Soft-revoke a device registration (preserves audit). After revocation the device can no longer scan events that require device registration.","security":[{"bearerAuth":[]}],"parameters":[{"name":"registrationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id"],"properties":{"venue_event_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Device registration revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ScannerDevice"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Event not found for this tenant (`event_not_found`), or no active device registration of that event with this id."},"502":{"description":"Device revoke could not be completed."}}}},"/v1/tickets/validate":{"post":{"tags":["scanning"],"summary":"Scanner-device online validate","operationId":"validateTicket","description":"Authenticated by x-scanner-token scoped to venue_event_id. Outcome in data.result_code (HTTP 200). A scanner token assigned to a door station that does not admit the ticket's tier returns wrong_door without consuming the ticket.","security":[{"scannerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_code","venue_event_id"],"properties":{"qr_code":{"type":"string"},"venue_event_id":{"type":"string","format":"uuid"},"client_device_id":{"type":"string","maxLength":128}}}}}},"responses":{"200":{"description":"Validation outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ScanResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Scanner token not authorized (returned as data.result_code=scanner_not_authorized)."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/tickets/scanner-manifest":{"get":{"tags":["scanning"],"summary":"Offline scan manifest (query)","description":"Dual auth: volunteer `x-scanner-token`, or staff Bearer JWT + `x-tenant-id` with a scanner role and active event grant. Prefer staff JWT for operator Sync (ENG-613 option A).","operationId":"getScannerManifestByQuery","security":[{"scannerToken":[]},{"bearerAuth":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TenantIdHeader"}],"responses":{"200":{"description":"Manifest of tickets + live QR verification keys + active device sessions for offline authoritative verify (HF-022 ≥12h window). `qr_key_metadata` = `{ format: 'ed25519-v1', active_kid, revoked_kids[], keys[]: { kid, alg: 'Ed25519', public_key } }` (raw 32-byte public key, base64url). Public keys only: a door verifies any v3 code offline and can mint none; the response never carries signing material.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Missing scanner token and staff JWT."},"403":{"description":"Scanner token or staff grant not authorized."},"404":{"$ref":"#/components/responses/NotFound"},"503":{"description":"Live QR verification keys not configured on the service."}}}},"/v1/tickets/manifest/{eventId}":{"get":{"tags":["scanning"],"summary":"Offline scan manifest (path)","description":"Dual auth: volunteer `x-scanner-token`, or staff Bearer JWT + `x-tenant-id` with a scanner role and active event grant.","operationId":"getScannerManifestByPath","security":[{"scannerToken":[]},{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TenantIdHeader"}],"responses":{"200":{"description":"Manifest (same shape as /scanner-manifest).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Missing scanner token and staff JWT."},"403":{"description":"Scanner token or staff grant not authorized."},"404":{"$ref":"#/components/responses/NotFound"},"503":{"description":"Live QR verification keys not configured on the service."}}}},"/v1/tickets/sync-scans":{"post":{"tags":["scanning"],"summary":"Sync offline scans (device token)","operationId":"syncScans","description":"Batch of offline scans (max 500); each item is scoped to its venue_event_id by x-scanner-token.","security":[{"scannerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scans":{"type":"array","maxItems":500,"items":{"type":"object","required":["qr_code","venue_event_id"],"properties":{"qr_code":{"type":"string"},"venue_event_id":{"type":"string","format":"uuid"},"scan_id":{"type":"string"},"scanned_at":{"type":"string","format":"date-time","description":"Phone scan time. Drain verifies the QR at this instant, inside a 72h pack-cap late window and a one-slot future bound. Missing or out-of-bounds values return conflict scanned_at_out_of_bounds and drop the queue row. Not required in the JSON schema because the route still accepts the request and classifies the item."},"device_id":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Per-item results + summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"summary":{"type":"object"},"results":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/tickets/sync-scans-staff":{"post":{"tags":["scanning"],"summary":"Sync offline scans (staff JWT)","operationId":"syncScansStaff","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scans":{"type":"array","maxItems":500,"items":{"type":"object","required":["qr_code"],"properties":{"qr_code":{"type":"string"},"pending_staff_sync":{"type":"boolean"},"pending_online_validation":{"type":"boolean"},"scan_id":{"type":"string"},"scanned_at":{"type":"string","format":"date-time","description":"Phone scan time. Drain verifies the QR at this instant, inside a 72h pack-cap late window and a one-slot future bound. Missing or out-of-bounds values return conflict scanned_at_out_of_bounds and drop the queue row. Not required in the JSON schema because the route still accepts the request and classifies the item."},"device_id":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Per-item results + summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}}},"/v1/tenants/{tenantId}/orders":{"get":{"tags":["tenants"],"summary":"List the organization's orders (ENG-3035)","description":"Newest first. Filter by `event_id` or `production_id` (a series lists the orders sold under it, by the series recorded on each order, so a long run never puts its shows in the URL), `ticket_tier_id`, `status`, and `q`: the buyer's name or email, or the start of an order number. Each row carries its lines (ticket type, show and start in the show's time zone, seats), add-ons, wallet and one display status. Needs tenant_orders.read (an event-scoped grant reads its own event with `event_id`). A viewer gets the buyer's email masked and no name or phone, and searches by order number only.","operationId":"listTenantOrders","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"production_id","in":"query","required":false,"description":"A series. Not with event_id.","schema":{"type":"string","format":"uuid"}},{"name":"ticket_tier_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["reserved","pending_payment","processing","paid","cancelled","failed","expired","awaiting_cash","partially_refunded","refunded"]}},{"name":"display_status","in":"query","required":false,"description":"ENG-3037. Orders whose `display_status` is this one. `not_cancelled` (ENG-3262) is every order but a checkout that never paid. With `status`, both apply.","schema":{"type":"string","enum":["paid","pending","refunded","partially_refunded","cancelled","not_cancelled"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderListRow"}},"total_count":{"type":"integer"},"cancelled_count":{"type":"integer","description":"ENG-3262. Checkouts that never paid (`display_status` `cancelled`) under every filter but `display_status`."},"next_offset":{"type":"integer","nullable":true}}}}}}}},"400":{"description":"A filter is not valid, or both event_id and production_id were given."},"401":{"description":"Authenticated staff required."},"403":{"description":"No tenant_orders.read grant."},"404":{"description":"event_not_found or production_not_found."},"502":{"description":"The read failed."}}}},"/v1/tenants/{tenantId}/orders/{orderId}":{"get":{"tags":["tenants"],"summary":"One order as the order panel shows it (ENG-3035)","description":"The order with its lines, add-ons, tickets (holder, who passed it on, show, seat), saved sessions, paid upgrades, ticket type moves, coupons, where it was bought, checkout answers, cash at the door, the staff it names, refund requests, payments and its money from the same computation as the Overview. An order of another organization answers the same 404 as an unknown one. Needs tenant_order.drill. A viewer gets no buyer or guest names, masked emails and no answers.","operationId":"getTenantOrder","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/TenantOrderDrill"}}}}}},"400":{"description":"tenantId or orderId is not a UUID."},"401":{"description":"Authenticated staff required."},"403":{"description":"No tenant_order.drill grant."},"404":{"description":"order not found"},"502":{"description":"The read failed."}}}},"/v1/tenants/{tenantId}/dashboard/funnel-report":{"get":{"tags":["tenants"],"summary":"How buyers convert, for an event or a series (ENG-2313, ENG-2321)","description":"Every funnel step, why visitors stopped, value left behind, time to buy, each ticket and pass type, and performance by channel, place, device and where they bought. A visitor is one person as far as AXYN can tell: the 30-day visitor id when they allowed one, else the browser tab. Money is each paid order priced as on the Sales dashboard, so every table adds up to the Sales total; an order with no recorded journey has its own row. Give exactly one of `event_id` or `series_id`. A program inside a series has no report of its own (409 with its `series_id`). Needs sales_dashboard.read. A caller who also holds guest_list.read for the whole organization, other than a viewer (whose guest list is masked), gets `buyer_places` and every live place with no 5-visitor Other grouping; saved 13-month place totals keep their minimum (ENG-2769).","operationId":"getFunnelReport","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"The event. Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}},{"name":"series_id","in":"query","required":false,"description":"The series. Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"First day, in the event's own time zone. Visitors are placed by the day they were first seen, orders by the day they were paid.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, inclusive.","schema":{"type":"string","format":"date"}},{"name":"credit","in":"query","required":false,"description":"Which visit gets the credit for a visitor: their first (default) or the one that bought.","schema":{"type":"string","enum":["first","converting"],"default":"first"}},{"name":"show_id","in":"query","required":false,"description":"Series only: narrow to visitors who were on this show's page, and to its orders. A narrowed report covers visitors whose ids still exist (the last 13 months).","schema":{"type":"string","format":"uuid"}},{"name":"ticket_type_id","in":"query","required":false,"description":"Narrow to visitors who picked this ticket or pass type, and to orders that hold it.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"scope":{"type":"object","properties":{"kind":{"type":"string","enum":["event","series"]},"id":{"type":"string","format":"uuid"},"timezone":{"type":"string"},"starts_on":{"type":["string","null"],"format":"date","description":"The day the event (or the series' first program) starts, in its own time zone."}}},"range":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}}},"credit":{"type":"string","enum":["first","converting"]},"small_sample_below":{"type":"integer","description":"A rate on fewer visitors than this should be shown with a small-sample note."},"steps":{"type":"array","description":"Visitors who reached at least each step. Never grows down the list.","items":{"type":"object","properties":{"step":{"type":"string","enum":["viewed","chose_tickets","entered_details","started_checkout","opened_payment","paid"]},"visitors":{"type":"integer"}}}},"detail_recorded":{"type":"boolean","description":"False when only the original four steps were recorded for the period."},"stop_reasons":{"type":"array","description":"One final reason per visitor who did not buy. They add up to those visitors.","items":{"type":"object","properties":{"reason":{"type":"string","enum":["could_not_buy","left_after_viewing","left_after_choosing","left_at_details","left_at_checkout","left_at_payment","payment_failed","timer_ran_out"]},"visitors":{"type":"integer"}}}},"paid_after_failed_payment":{"type":"integer"},"value_left_cents":{"type":"integer","description":"List value of what unpaid visitors last had in hand. Not discounted."},"time_to_buy":{"type":["object","null"],"description":"First view to first purchase. Null with no tracked buyers.","properties":{"p25_seconds":{"type":"integer"},"median_seconds":{"type":"integer"},"p75_seconds":{"type":"integer"},"approximate":{"type":"boolean","description":"True when some buyers are older than 13 months: their time to buy is kept only as a band, so the figures are the upper edge of the band they fall in."}}},"ticket_types":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"is_pass":{"type":"boolean"},"section":{"type":"string","nullable":true,"description":"The seating section this type sells, when it sells one."},"wanted":{"type":"integer"},"started":{"type":"integer"},"bought":{"type":"integer"},"value_left_cents":{"type":"integer"}}}},"type_not_reported":{"type":"integer","description":"Visitors who chose tickets without saying which type."}}},"totals":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Totals: every sale except partner-reported ones (orders with no recorded visit and door sales stay in) / visitors. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"archived":{"type":"boolean"},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down (source / medium, then campaign)."}}},"channels":{"type":"array","items":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Sales from recorded visits / visitors: partner-reported sales are left out. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"landed_day":{"type":"string","format":"date","description":"On a link row, or a source / medium row's campaign row, once it has landed: the first day in the event's time zone with 25 or more visitors credited to it first, or 10 or more that are at least 25% of that day's visitors. One per campaign, ever; the same whatever range or credit is asked for."},"landed_window":{"type":"object","description":"With landed_day: visitors credited to it first over the landed day and the 6 days after, and those of them with a paid order.","properties":{"visitors":{"type":"integer"},"buyers":{"type":"integer"}}},"archived":{"type":"boolean"},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down (source / medium, then campaign)."}}}},"bought_at":{"type":"array","items":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Sales from recorded visits / visitors: partner-reported sales are left out. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"archived":{"type":"boolean"},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down (source / medium, then campaign)."}}}},"places":{"type":"array","items":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Sales from recorded visits / visitors: partner-reported sales are left out. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"archived":{"type":"boolean"},"latitude":{"type":"number","description":"ENG-2359: on a city row only (key `city:<CC>-<RR>:<city name>`, label = the city name): the mean of that city's journeys' approximate points, rounded to 2 decimals. Absent on country, region and Other rows."},"longitude":{"type":"number","description":"ENG-2359: on a city row only; see latitude."},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down: regions (`CC-RR`) under a country, then cities (`city:CC-RR:<city name>`, with latitude and longitude) under a region (ENG-2359). Fewer than 5 visitors fold into `too_few` at each level."}}}},"devices":{"type":"array","items":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Sales from recorded visits / visitors: partner-reported sales are left out. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"archived":{"type":"boolean"},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down (source / medium, then campaign)."}}}},"paid_with":{"type":"array","description":"ENG-2787: How they paid. Paid online orders (door sales left out) by the method the buyer actually paid with, most orders first. A refunded order counts as everywhere else in Conversion; `paid_cents` is what buyers paid on the order charge, fees and tax included, less that order's refunds. Upgrade charges are left out.","items":{"type":"object","required":["key","label","orders","share_bps","paid_cents"],"properties":{"key":{"type":"string","enum":["apple_pay","card","google_pay","link","other","not_recorded"]},"label":{"type":"string"},"orders":{"type":"integer"},"share_bps":{"type":["integer","null"],"description":"Share of online orders in basis points; null when there are fewer than 5 online orders."},"paid_cents":{"type":"integer"}}}},"entry_pages":{"type":"array","description":"Series only: the page visitors came in through.","items":{"type":"object","description":"One row of a breakdown. Rows of a table add up to `totals`.","properties":{"key":{"type":"string"},"label":{"type":"string"},"visitors":{"type":"integer"},"chose":{"type":"integer"},"started":{"type":"integer"},"paid_visitors":{"type":"integer","description":"Visitors with at least one paid order."},"orders":{"type":"integer"},"tickets":{"type":"integer"},"gross_cents":{"type":"integer","description":"Priced by the same rule as the Sales dashboard."},"partner_reported_orders":{"type":"integer","description":"ENG-2575: orders of this row with no recorded visit, credited from the UTM tags the selling partner sent with the order (checkout_utm_*). Part of orders; never a visitor or a buyer. 0 outside the channel table."},"partner_reported_gross_cents":{"type":"integer","description":"ENG-2575: the sales of partner_reported_orders. Part of gross_cents."},"conversion_bps":{"type":["integer","null"],"description":"paid_visitors / visitors in basis points; null with no visitors."},"average_order_cents":{"type":["integer","null"]},"sales_per_visitor_cents":{"type":["integer","null"],"description":"Sales from recorded visits / visitors: partner-reported sales are left out. Null with no visitors."},"tracking_link_id":{"type":"string","format":"uuid","description":"Set on a named tracking link's row."},"archived":{"type":"boolean"},"children":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The same row shape, one level down (source / medium, then campaign)."}}}},"by_day":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"visitors":{"type":"integer"},"orders":{"type":"integer"},"gross_cents":{"type":"integer"}}}},"has_money":{"type":"boolean","description":"False for a free event."},"email_nudge":{"type":"boolean","description":"Direct holds 40% or more of 100 or more recorded visitors and Email under 100: the \"See what your emails sell\" nudge is due. Whether this member hid it is GET /v1/tenants/{tenantId}/email-nudge."},"saved_visitors":{"type":"integer","description":"Visitors in this report that come from totals saved when their ids were removed at 13 months. Time to buy and ticket types cover the other visitors only. A saved group of fewer than 5 visitors is shown as one Other row."},"coverage":{"type":"object","description":"How much of the picture this is: paid orders placed online, how many came with a recorded visit, how many more a selling partner reported the channel of with UTM tags on the order (ENG-2575), and funnel steps turned away.","properties":{"online_orders":{"type":"integer"},"tracked_orders":{"type":"integer"},"partner_reported_orders":{"type":"integer","description":"Online orders with no recorded visit whose channel and campaign come from the checkout_utm_* the selling partner sent with the order. Not in tracked_orders."},"dropped_steps":{"type":"integer"}}},"buyer_places":{"type":"object","description":"ENG-2769: the report's paid orders by the postal code the buyer typed at checkout, every postal code its own row (no Other folding). Present only when the caller also holds guest_list.read for the whole organization and is not a viewer alone; absent otherwise. An erased buyer's order is not counted.","required":["points","no_map_point","no_location"],"properties":{"points":{"type":"array","description":"Postal codes with a map point, most buyers first.","items":{"type":"object","required":["key","postal_code","city","country_code","region_code","latitude","longitude","buyers","orders"],"properties":{"key":{"type":"string"},"postal_code":{"type":"string"},"city":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"region_code":{"type":"string","nullable":true},"latitude":{"type":"number","description":"The postal code's point, rounded to 2 decimals (about 1 km)."},"longitude":{"type":"number"},"buyers":{"type":"integer"},"orders":{"type":"integer"}}}},"no_map_point":{"type":"array","description":"Buyers whose postal code gives no map point, by country and state.","items":{"type":"object","required":["key","country_code","region_code","buyers","orders"],"properties":{"key":{"type":"string"},"country_code":{"type":"string","nullable":true},"region_code":{"type":"string","nullable":true},"buyers":{"type":"integer"},"orders":{"type":"integer"}}}},"no_location":{"type":"object","description":"Paid orders whose buyer typed no postal code.","required":["buyers","orders"],"properties":{"buyers":{"type":"integer"},"orders":{"type":"integer"}}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The event is a program inside a series; its journeys count toward the series.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["event_in_series"]},"series_id":{"type":"string","format":"uuid"}}}}}}}}},"/v1/tenants/{tenantId}/overview-moves":{"get":{"tags":["tenants"],"summary":"Ways to sell more: the ideas an event or series qualifies for (ENG-2405)","description":"The Risk, Forecast and Geography ideas a standalone event or a series qualifies for on its Overview, as facts with every number they show: behind on-sale types and shared areas (largest money at risk first) with the non-discount idea first and a 10% code only in the final 14 days or with no visible cause; the type that sells out first with the comps it could release; a city whose share of visitors and buyers differ by 2x. Read only; nothing is created. A show inside a series has none (409). Needs sales_dashboard.read.","operationId":"getOverviewMoves","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"Exactly one of event_id or production_id.","schema":{"type":"string","format":"uuid"}},{"name":"production_id","in":"query","required":false,"description":"Exactly one of event_id or production_id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OverviewMoves"}}}}}},"400":{"description":"Not exactly one event_id or production_id as a UUID."},"401":{"description":"Not signed in."},"403":{"description":"No sales_dashboard.read."},"404":{"description":"No such event or series for this organizer."},"409":{"description":"A show inside a series: its series has the ideas (`event_in_series`, with `series_id`)."},"502":{"description":"The ideas could not be read."}}},"post":{"tags":["tenants"],"summary":"Open a Ways to sell more idea (ENG-2405)","description":"The idea's button was pressed. Returns the idea's move with the prefill its screen fills in: the one pending move is opened (again), its prefill refreshed from the idea as it stands and any Not now cleared; a move whose 7-day window is still running is returned as it is. Nothing else is created. Opening is a write, so it needs the permission its link will: comp_hold.manage for a comp release, event.write for every other idea (finance and viewers are refused).","operationId":"openOverviewMove","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewMoveIdea"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OverviewMove"}}}}}},"400":{"description":"Not exactly one event_id or production_id, or a bad kind or target."},"401":{"description":"Not signed in."},"403":{"description":"No comp_hold.manage (comp release) or event.write (every other idea)."},"404":{"description":"No such event or series for this organizer."},"409":{"description":"`idea_gone`: the event or series no longer has this idea; or `event_in_series`."},"502":{"description":"The move could not be saved."}}}},"/v1/tenants/{tenantId}/overview-moves/snooze":{"post":{"tags":["tenants"],"summary":"Not now: hide a Ways to sell more idea for 7 days (ENG-2405)","description":"Hides the idea for the whole team for 7 days, or until its gap moves more than 25% from now. Needs event.write.","operationId":"snoozeOverviewMove","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewMoveIdea"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["snoozed_until"],"properties":{"snoozed_until":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Not exactly one event_id or production_id, or a bad kind or target."},"401":{"description":"Not signed in."},"403":{"description":"No event.write."},"404":{"description":"No such event or series for this organizer."},"409":{"description":"`move_started` (its window is still running), `idea_gone` or `event_in_series`."},"502":{"description":"The snooze could not be saved."}}}},"/v1/tenants/{tenantId}/overview-moves/{moveId}":{"get":{"tags":["tenants"],"summary":"A Ways to sell more move and its prefill (ENG-2405)","description":"The prefill a screen opened with ?move={id} reads; nothing in the link itself fills a field. Needs sales_dashboard.read.","operationId":"getOverviewMove","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OverviewMove"}}}}}},"400":{"description":"tenantId or moveId is not a UUID."},"401":{"description":"Not signed in."},"403":{"description":"No sales_dashboard.read."},"404":{"description":"No such move for this organizer."},"502":{"description":"The move could not be read."}}}},"/v1/tenants/{tenantId}/overview-moves/{moveId}/link":{"post":{"tags":["tenants"],"summary":"Start a Ways to sell more move by linking what was saved (ENG-2405)","description":"Called right after the code, comp hold or tracking link the move opened was saved. Accepted only when it is in the move's organizer and event or series, fits the idea (a code covering the idea's types, a comp hold on its type now holding fewer, a tracking link) and was made or changed after the move opened. The move is then started and what it was expected to sell anyway over its window (7 days, or to the show start or sale end) is frozen from the forecast. A coupon or tracking link needs event.write; a comp hold needs comp_hold.manage.","operationId":"linkOverviewMove","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Exactly one. `city_list: true` starts a city campaign from its copied or downloaded city list, with nothing to link.","properties":{"coupon_id":{"type":"string","format":"uuid"},"hold_id":{"type":"string","format":"uuid"},"tracking_link_id":{"type":"string","format":"uuid"},"city_list":{"type":"boolean","enum":[true]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OverviewMove"}}}}}},"400":{"description":"Not exactly one coupon_id, hold_id or tracking_link_id as a UUID."},"401":{"description":"Not signed in."},"403":{"description":"No event.write (coupon, tracking link) or comp_hold.manage (hold)."},"409":{"description":"`move_already_started`."},"422":{"description":"`move_link_invalid` with `reason`: move_not_found, not_opened, wrong_link_kind, not_in_scope, not_covered, before_open, hold_not_reduced or window_closed. The move stays opened."},"502":{"description":"The link could not be saved."},"503":{"description":"`forecast_unavailable`: the forecast could not be read just now, so nothing was frozen. The move stays opened; retry."}}}},"/v1/tenants/{tenantId}/email-nudge":{"get":{"tags":["tenants"],"summary":"Whether this member hid the email nudge (ENG-2565)","description":"\"See what your emails sell\" on an event's or series' Conversion page. When it is due is the funnel report's `email_nudge`; this says whether the signed-in member hid it there. Needs sales_dashboard.read.","operationId":"getEmailNudge","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}},{"name":"series_id","in":"query","required":false,"description":"Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"hidden":{"type":"boolean","description":"This member hid the email nudge on this event or series."}}}}}}}},"400":{"description":"Not exactly one event_id or series_id as a UUID, or `hidden` is not a boolean."},"401":{"description":"No member: an API key alone has no one to hide it for."},"403":{"description":"No sales_dashboard.read."},"404":{"description":"The event or series is not this organizer's."}}},"put":{"tags":["tenants"],"summary":"Hide or show the email nudge for this member (ENG-2565)","description":"Hides it (or shows it again) for the signed-in member on one event or series only; other members still see it. Needs sales_dashboard.read.","operationId":"setEmailNudge","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hidden"],"properties":{"event_id":{"type":"string","format":"uuid","description":"Exactly one of event_id or series_id."},"series_id":{"type":"string","format":"uuid","description":"Exactly one of event_id or series_id."},"hidden":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"hidden":{"type":"boolean","description":"This member hid the email nudge on this event or series."}}}}}}}},"400":{"description":"Not exactly one event_id or series_id as a UUID, or `hidden` is not a boolean."},"401":{"description":"No member: an API key alone has no one to hide it for."},"403":{"description":"No sales_dashboard.read."},"404":{"description":"The event or series is not this organizer's."}}}},"/v1/tenants/{tenantId}/tracking-links":{"get":{"tags":["tenants"],"summary":"Named tracking links of an event or series (ENG-2322)","description":"Active links first, then archived. A link is a label on a visit: it never unlocks a price, a hold or a discount. Needs sales_dashboard.read.","operationId":"listTrackingLinks","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}},{"name":"series_id","in":"query","required":false,"description":"Exactly one of event_id or series_id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"channels":{"type":"array","description":"The channels a link can be given, for the picker.","items":{"type":"string","enum":["print","radio","email","social","partner","other"]}},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"code":{"type":"string","description":"Short and random. Says nothing about anyone."},"param":{"type":"string","description":"The address parameter that carries the code: `?axl=<code>`."},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["tenants"],"summary":"Name a tracking link (ENG-2322)","description":"Names are unique per event or series whatever their capitals and spacing; a duplicate answers 409 with the existing link. Up to 50 active links per event or series. Needs event.write.","operationId":"createTrackingLink","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","channel"],"properties":{"event_id":{"type":"string","format":"uuid"},"series_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":60},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"code":{"type":"string","description":"Short and random. Says nothing about anyone."},"param":{"type":"string","description":"The address parameter that carries the code: `?axl=<code>`."},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The name is already used here (`name_taken`, with the existing link), or the event or series already has its 50 active links (`too_many_active_links`).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["name_taken","too_many_active_links"]},"data":{"type":"object","properties":{"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"code":{"type":"string","description":"Short and random. Says nothing about anyone."},"param":{"type":"string","description":"The address parameter that carries the code: `?axl=<code>`."},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"}}},"max_active":{"type":"integer"}}}}}}}}}}},"/v1/tenants/{tenantId}/tracking-links/{linkId}":{"patch":{"tags":["tenants"],"summary":"Rename, move, archive or restore a tracking link (ENG-2322)","description":"There is no delete. An archived link leaves the picker, keeps its history and still credits anyone who uses it. The code never changes. Needs event.write.","operationId":"updateTrackingLink","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"linkId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":60},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"archived":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"code":{"type":"string","description":"Short and random. Says nothing about anyone."},"param":{"type":"string","description":"The address parameter that carries the code: `?axl=<code>`."},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The name is already used here (`name_taken`, with the existing link), or the event or series already has its 50 active links (`too_many_active_links`).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["name_taken","too_many_active_links"]},"data":{"type":"object","properties":{"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["print","radio","email","social","partner","other"]},"code":{"type":"string","description":"Short and random. Says nothing about anyone."},"param":{"type":"string","description":"The address parameter that carries the code: `?axl=<code>`."},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"}}},"max_active":{"type":"integer"}}}}}}}}}}},"/v1/tenants/{tenantId}/dashboard/series/{productionId}/checkout-funnel":{"get":{"tags":["tenants"],"summary":"Checkout funnel of a series (ENG-2309)","description":"One funnel for all the programs and passes of a series: journeys are the funnel facts recorded for the series, Paid is every paid order on any of its programs. Steps are null (shown as N/A) when nothing was recorded; a rate is never invented. A program inside a series has no funnel of its own. Needs sales_dashboard.read.","operationId":"getSeriesCheckoutFunnel","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The series funnel","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"conversion_mix":{"type":"object","properties":{"by_domain":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"sessions":{"type":"integer"},"paid_orders":{"type":"integer"},"cvr_bps":{"type":["integer","null"],"description":"Paid orders per session, in basis points. Null when there are no sessions."}}}},"by_surface":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"sessions":{"type":"integer"},"paid_orders":{"type":"integer"},"cvr_bps":{"type":["integer","null"],"description":"Paid orders per session, in basis points. Null when there are no sessions."}}}},"by_integration":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"sessions":{"type":"integer"},"paid_orders":{"type":"integer"},"cvr_bps":{"type":["integer","null"],"description":"Paid orders per session, in basis points. Null when there are no sessions."}}}},"total_sessions":{"type":"integer"},"total_paid_orders":{"type":"integer"},"overall_cvr_bps":{"type":["integer","null"]},"headless_pageviews":{"type":"string","enum":["n_a","tracked"]},"visitors":{"type":"object","description":"Visitors who allowed the 30-day visitor id (ENG-2319). Counts are zero and medians null when there are none.","properties":{"visitors":{"type":"integer","description":"Distinct visitors with the 30-day id."},"returning_visitors":{"type":"integer","description":"Visitors who came back for a second visit or more (a visit ends after 30 minutes with no step)."},"converted_visitors":{"type":"integer","description":"Visitors with at least one paid online order; a visitor with two orders counts once."},"converted_returning_visitors":{"type":"integer","description":"Converted visitors who bought on a later visit than their first."},"median_visits_to_purchase":{"type":["number","null"],"description":"Median visits up to and including the one that bought; null with no buyers."},"median_days_to_purchase":{"type":["number","null"],"description":"Median whole days from first visit to first purchase; null with no buyers."}}},"coverage":{"type":"object","description":"How much of the picture the funnel has (ENG-2312). Orders that came with a journey give a real per-journey conversion; the rest are counted in Paid and named untracked.","properties":{"online_paid_orders":{"type":"integer","description":"Paid orders placed online; door sales are outside the online funnel."},"tracked_paid_orders":{"type":"integer"},"paid_journeys":{"type":"integer","description":"Distinct journeys that ended in at least one paid order."},"journey_cvr_bps":{"type":["integer","null"],"description":"paid_journeys / journeys in basis points; null with nothing tracked."},"dropped_steps":{"type":"integer","description":"Funnel steps AXYN turned away for this event or series (rate limit, or no room while orders had priority). Above zero, the step counts are a floor."}}},"funnel":{"type":"object","properties":{"viewed":{"type":["integer","null"]},"chose_tickets":{"type":["integer","null"]},"started_checkout":{"type":["integer","null"]},"paid":{"type":"integer","description":"Paid orders, from orders, never from a beacon."},"steps_available":{"type":"boolean"}}}}},"partner_page_insights":{"type":"object","properties":{"status":{"type":"string","enum":["tracking","enabled_not_installed","off","sparse"]},"enabled":{"type":"boolean"},"last_signal_at":{"type":["string","null"],"format":"date-time"},"headless_paid_orders":{"type":"integer"},"headless_view_sessions":{"type":"integer"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tenants/{tenantId}/venues/address-suggestions":{"get":{"tags":["catalog"],"summary":"Suggest venue addresses while typing","description":"Up to five street addresses matching what the organizer has typed, already split into the venue address columns. For display only: results come from Mapbox temporary geocoding and must not be stored; send the picked label to address-lookup before saving a venue. Queries under 3 characters return no suggestions. When address lookup is not configured or the provider fails, returns 200 with available: false so the caller can fall back to typing the parts. Needs event.write. Path tenantId must match the API key tenant. Rate limited per caller.","operationId":"suggestVenueAddresses","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200},"description":"What the organizer typed."},{"name":"country","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Optional ISO country to bias results, like US."}],"responses":{"200":{"description":"Suggestions (possibly empty).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"One line to show and to send to address-lookup."},"address_line1":{"type":"string"},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2, upper case."}},"required":["label","address_line1"]}},"available":{"type":"boolean","description":"False when address lookup is off or failing."}},"required":["suggestions","available"]}}},"example":{"success":true,"data":{"suggestions":[{"label":"1350 Third Street, Napa, California 94559, United States","address_line1":"1350 Third Street","city":"Napa","region":"CA","postal_code":"94559","country":"US"}],"available":true}}}}},"400":{"description":"tenantId is not a UUID, or q is longer than 200 characters."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/tenants/{tenantId}/venues/address-lookup":{"post":{"tags":["catalog"],"summary":"Look up the address picked for a venue","description":"Looks up one address (usually a label from address-suggestions) in Mapbox permanent mode and returns its parts and map coordinates, which may be stored. Pass them to POST /v1/tenants/{tenantId}/venues (latitude and longitude included) so the venue is not geocoded twice. Needs event.write. Path tenantId must match the API key tenant. Rate limited per caller.","operationId":"lookupVenueAddress","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":3,"maxLength":200},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Optional ISO country bias."}},"required":["query"],"example":{"query":"1350 Third Street, Napa, California 94559, United States","country":"US"}}}}},"responses":{"200":{"description":"The address, split into columns, with coordinates.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"address":{"type":"object","properties":{"label":{"type":"string","description":"One line to show and to send to address-lookup."},"address_line1":{"type":"string"},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2, upper case."},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["label","address_line1","latitude","longitude"]}}}}}}}},"400":{"description":"query is missing, shorter than 3 or longer than 200 characters, or tenantId is not a UUID."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"address_not_found: no street address matches the query."},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"address_lookup_unavailable: the address provider failed."},"503":{"description":"address_lookup_unavailable: address lookup is not configured."}}}},"/v1/tenants/{tenantId}/venues/{venueId}":{"patch":{"tags":["catalog"],"summary":"Finish a venue's missing address (ENG-1772)","description":"Adds the street, city and other address parts to a venue that was created without them, so its events can publish (publish needs address_line1 and city). Fill-only: it sets parts that are empty and never changes or clears a part that is already set (409 venue_address_locked). Sending a part with the value it already has is fine. Only works while address_line1, city or timezone is still empty; the save must leave all three set, and once they are the address is locked. A venue with a street and city but no timezone can still add one. Blank strings are treated as null. When the venue has no map location yet, one is looked up from the address. Path tenantId must match the API key tenant.","operationId":"completeVenueAddress","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"venueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address_line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"timezone":{"type":["string","null"],"description":"IANA time zone, like America/Los_Angeles."}},"example":{"address_line1":"1350 Third Street","city":"Napa","region":"CA","postal_code":"94559","country":"US","timezone":"America/Los_Angeles"}}}}},"responses":{"200":{"description":"Venue with its address filled in.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"venue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"address_line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"timezone":{"type":["string","null"]},"status":{"type":"string"},"has_seating":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}}},"400":{"description":"venue_address_incomplete (street, city or timezone would still be empty), a non-string field, or a timezone that is not an IANA zone."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"venue_address_locked: the venue already has a street, city and timezone, or the request tried to change a part that is already set."}}}},"/v1/tenants/{tenantId}/venues/{venueId}/house":{"get":{"tags":["catalog"],"summary":"Get venue house geometry (ENG-720)","description":"Tenant-scoped house copy (geometry only, not live event inventory). Path tenantId must match the API key tenant. Requires event.read. Sandbox: use your test tenant UUID, never a production tenant id.","operationId":"getVenueHouse","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"venueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Venue house payload.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/VenueHouse"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["catalog"],"summary":"Replace venue house geometry (ENG-720)","description":"Full replace of venue house sections/seats (copy store, not live event inventory). When has_seating is already true, confirm_overwrite must be true. Path tenantId must match the API key tenant.","operationId":"replaceVenueHouse","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"venueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sections"],"properties":{"confirm_overwrite":{"type":"boolean"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/VenueHouseSection"}}},"example":{"confirm_overwrite":true,"sections":[{"name":"Orchestra","display_order":0,"seats":[{"row_label":"A","seat_number":"1","accessible":false}]}]}}}}},"responses":{"200":{"description":"Updated venue house.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/VenueHouse"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"overwrite_confirm_required"}}}},"/v1/tenants/{tenantId}/connect/onboarding-link":{"post":{"tags":["connect"],"summary":"Create a Stripe Connect onboarding link","operationId":"createConnectOnboardingLink","description":"ENG-356: staff JWT + organizer_admin (or super_admin). Optional x-api-key must match path tenantId.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_url","refresh_url"],"properties":{"return_url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS required; http://localhost and http://127.0.0.1 allowed for local admin."},"refresh_url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS required; http://localhost and http://127.0.0.1 allowed for local admin."},"force_new":{"type":"boolean","description":"When true, create a new Stripe Connect account and replace the stored external id, then mint an Account Link for the new account. Use when Express keeps opening a stuck prior login. Refused with 409 if charges and payouts are already enabled."}}}}}},"responses":{"201":{"description":"Onboarding link.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"url":{"type":"string"},"expires_at":{"type":"integer"},"status":{"type":"string","enum":["pending","active","restricted","disabled"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"force_new refused because Connect is already fully active.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"code":{"type":"string","enum":["connect_replace_not_allowed"]}}}}}},"422":{"description":"Stripe rejected Connect account or Account Link creation as a business/config error (e.g. platform profile incomplete). Not retryable until the platform is fixed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","description":"Stripe's error message, passed through verbatim."},"code":{"type":"string","enum":["stripe_platform_profile_incomplete","stripe_invalid_request"]}}}}}},"502":{"$ref":"#/components/responses/PaymentGatewayError"},"503":{"description":"Stripe not configured, or Stripe unavailable / rate limited / rejected the platform key (code stripe_unavailable). Retryable.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","description":"Stripe's error message, passed through verbatim."},"code":{"type":"string","enum":["stripe_unavailable"]}}}}}}}}},"/v1/tenants/{tenantId}/connect/account":{"get":{"tags":["connect"],"summary":"Get the tenant's Connect account status","operationId":"getConnectAccount","description":"ENG-356: staff JWT + organizer_admin (or super_admin). Optional x-api-key must match path tenantId.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Connect account view.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ConnectAccountView"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Internal error."}}}},"/v1/tenants/{tenantId}/workspace-defaults":{"get":{"tags":["tenants"],"summary":"Read workspace defaults for checkout contact, tax, and partner insights","operationId":"getTenantWorkspaceDefaults","description":"ENG-779: staff JWT with event.read. Returns typed workspace defaults; null means unset.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Workspace defaults.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WorkspaceDefaults"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"patch":{"tags":["tenants"],"summary":"Update workspace defaults","operationId":"patchTenantWorkspaceDefaults","description":"ENG-779: staff JWT with tenant.workspace_defaults.manage (organizer_admin). Null clears a default. Does not rewrite overridden or published events.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDefaults"}}}},"responses":{"200":{"description":"Updated workspace defaults.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WorkspaceDefaults"}}}}}},"400":{"description":"Validation failed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tenants/{tenantId}/buyer-payment-methods":{"get":{"tags":["tenants"],"summary":"Read How buyers can pay (Apple Pay, Google Pay, Link) and where wallets work","operationId":"getTenantBuyerPaymentMethods","description":"ENG-2789: staff JWT with settlement.read. The organization-wide wallet switches (cards are always accepted) and, per site the organizer's own checkout ran on, whether Apple Pay and Google Pay work there (ENG-2663). A sandbox workspace reads its own switches.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Switches and website status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["apple_pay","google_pay","link","sites"],"properties":{"apple_pay":{"type":"boolean"},"google_pay":{"type":"boolean"},"link":{"type":"boolean"},"sites":{"type":"array","items":{"type":"object","required":["site","working"],"properties":{"site":{"type":"string"},"working":{"type":"boolean"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"patch":{"tags":["tenants"],"summary":"Turn Apple Pay, Google Pay or Saved card (Link) on or off","operationId":"patchTenantBuyerPaymentMethods","description":"ENG-2789: staff JWT with tenant.workspace_defaults.manage (organizer_admin). Send one or more of apple_pay, google_pay, link as booleans; unknown fields are refused. Applies to checkout loaded after the change; a payment form already open keeps its buttons.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"apple_pay":{"type":"boolean"},"google_pay":{"type":"boolean"},"link":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The switches after the change."},"400":{"description":"Validation failed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tenants/{tenantId}/events/{eventId}/tier-upgrade-paths":{"get":{"tags":["upgrades","tenants"],"summary":"List allowed upgrade paths for an event","operationId":"listEventTierUpgradePaths","description":"ENG-813 / ENG-798. Empty list means buyer upgrades are off. Staff JWT with tier_upgrade_path.manage.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paths listed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["upgrades","tenants"],"summary":"Allow a source type to upgrade into a target type","operationId":"createEventTierUpgradePath","description":"ENG-813 / ENG-798. source_tier_id and target_tier_id required. Optional upgrade_deadline_hours_before_event (0-8760).","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source_tier_id","target_tier_id"],"properties":{"source_tier_id":{"type":"string","format":"uuid"},"target_tier_id":{"type":"string","format":"uuid"},"upgrade_deadline_hours_before_event":{"type":"integer","minimum":0,"maximum":8760,"nullable":true}}}}}},"responses":{"200":{"description":"Path already existed."},"201":{"description":"Path created."},"400":{"description":"Validation failed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tenants/{tenantId}/events/{eventId}/tier-upgrade-paths/{pathId}":{"delete":{"tags":["upgrades","tenants"],"summary":"Remove an allowed upgrade path","operationId":"deleteEventTierUpgradePath","description":"Blocks new buyer intents. Already-issued upgrade requests stay snapshot-immutable.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"pathId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Path deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tenants/{tenantId}/dashboard":{"get":{"tags":["tenants"],"summary":"Organizer sales dashboard","operationId":"getTenantSalesDashboard","description":"ENG-144 / ENG-2332. No filter: the portfolio (headline, events[], series[], event_counts). event_id: one event's Sales. production_id: a series' Sales in one request (series_sales, plus orders_summary, insights, channel_mix, promo_mix and velocity_series over the orders sold under the series; series_sales.door is check-ins over who was expected at the programs whose doors have opened, and attendance is null). event_id and production_id cannot be combined. An order sold under a series is reported on the series, never on a program: a program inside a series returns its own day tickets and door numbers, no money, no payout and no pass types, with production_id set. ENG-2399: `forecast` is the event's or series' sales forecast, whole run and per ticket/pass type, from the organizer's own past events blended with pooled similar events (medians and quartiles only, never another organizer's numbers); null with `forecast_reason` when there is nothing honest to show, null with no reason on the organization roll-up. `pace_status` and `expected_velocity` are read from the forecast. `latest_postponement` is the newest date move, if any. ENG-2402: `sales_series` (paid units, sales, orders and comps per day or week and per type; a series per pass plus Show tickets), `markers` and `facts` feed Sales over time; null / [] / null on the roll-up and for a program inside a series.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"production_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sales dashboard.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"orders_summary":{"type":"object"},"capacity":{"type":"array","items":{"type":"object"},"description":"Ticket types of the event asked for. For a program inside a series: its day ticket types only, without money."},"events":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"orders_count":{"type":"integer"},"tickets_count":{"type":"integer"},"gross_cents":{"type":"integer"},"net_cents":{"type":"integer"},"remaining":{"type":"integer","description":"Unsold units of the event's own ticket types. A pass type is never counted."},"production_id":{"type":"string","format":"uuid","nullable":true},"in_series":{"type":"boolean","description":"True for a program inside a series: orders_count, tickets_count, gross_cents and net_cents are 0."},"has_day_tickets":{"type":"boolean","description":"Present only when in_series."},"day_tickets_sold":{"type":"integer","description":"Present only when in_series."},"day_tickets_open":{"type":"integer","description":"Present only when in_series."},"partner_page_insights":{"type":"object"}}}},"audience":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SalesAudience"}],"description":"ENG-2408 B: the event's or series' buyers; null on the organization roll-up."},"comps_summary":{"type":"object","nullable":true},"inventory_mix":{"type":"object","nullable":true},"velocity_series":{"type":"array","items":{"type":"object"}},"velocity_by_tier":{"type":"array","items":{"type":"object"}},"pace_status":{"type":"string","nullable":true},"expected_velocity":{"type":"array","items":{"type":"object"}},"forecast":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastRun"},{"type":"null"}]},"forecast_reason":{"oneOf":[{"$ref":"#/components/schemas/SalesForecastReason"},{"type":"null"}]},"latest_postponement":{"type":["object","null"],"description":"ENG-2399: the event's latest postponement (a series: its next upcoming show's), or null.","properties":{"previous_starts_at":{"type":"string","format":"date-time"},"new_starts_at":{"type":"string","format":"date-time"},"postponed_at":{"type":"string","format":"date-time"}}},"forecast_types":{"type":"array","items":{"$ref":"#/components/schemas/SalesForecastTypeRow"},"description":"ENG-2480: every ticket type of the event or series in Setup order, whatever the forecast's state (empty on the organization-wide roll-up)."},"sales_series":{"oneOf":[{"$ref":"#/components/schemas/SalesSeries"},{"type":"null"}],"description":"ENG-2402: an event's or series' Sales over time. Null on the organization roll-up, for a program inside a series, and when it could not be read."},"markers":{"type":"array","items":{"$ref":"#/components/schemas/SalesMarker"},"description":"ENG-2402: what AXYN recorded on the run's days so far (on sale, discounts, tracking links, postponements, held programs going live)."},"facts":{"oneOf":[{"$ref":"#/components/schemas/SalesFacts"},{"type":"null"}],"description":"ENG-2402: the facts row (last 7 days, best day or week, buyers peak)."},"attendance":{"type":"object","nullable":true,"description":"One event's door. For a program inside a series it follows the series rule and also carries door (the series_sales.door shape for that one program): expected is its own live day tickets plus every live pass with an issued admit there, whichever program hosts the pass. Null on a series read."},"insights":{"type":"object"},"channel_mix":{"type":"object"},"promo_mix":{"type":"array","items":{"type":"object"}},"conversion_mix":{"type":"object","nullable":true},"upgrade_summary":{"type":"object","nullable":true},"payout":{"type":"object","nullable":true,"description":"Null for a program inside a series and for a series."},"partner_page_insights":{"type":"object","nullable":true},"production_id":{"type":"string","format":"uuid","nullable":true,"description":"The series of the program or series asked for; null for a standalone event and for the portfolio."},"series":{"type":"array","description":"Portfolio only: every series of the organizer with its totals and all of its programs.","items":{"type":"object","properties":{"production_id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"programs_count":{"type":"integer"},"orders_count":{"type":"integer","description":"Paid orders sold under the series (ticket_orders.production_id)."},"buyers_paid_cents":{"type":"integer","description":"Order totals, fees and tax included, before refunds."},"gross_cents":{"type":"integer","description":"Ticket sales, same meaning as events[].gross_cents."},"net_cents":{"type":"integer","description":"You keep, from the shared order money. Can be negative after refunds."},"refunds_cents":{"type":"integer"},"refunded_orders_count":{"type":"integer"},"passes_sold":{"type":"integer"},"day_tickets_sold":{"type":"integer"},"pass_comps":{"type":"integer"},"day_ticket_comps":{"type":"integer"},"programs":{"type":"array","items":{"type":"object","description":"A program inside a series: its own day tickets only. Never money, never a pass.","properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"The show's end time; null when none is set. Who's coming reads a show Live until it passes (ENG-2406)."},"has_day_tickets":{"type":"boolean","description":"False when the program sells no day ticket type (entry by pass)."},"day_tickets_sold":{"type":"integer"},"day_tickets_open":{"type":"integer"},"day_ticket_comps":{"type":"integer"}}}}}}},"series_sales":{"type":"object","nullable":true,"description":"Only with production_id: the series totals plus one row per ticket and pass type.","properties":{"production_id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"programs_count":{"type":"integer"},"orders_count":{"type":"integer","description":"Paid orders sold under the series (ticket_orders.production_id)."},"buyers_paid_cents":{"type":"integer","description":"Order totals, fees and tax included, before refunds."},"gross_cents":{"type":"integer","description":"Ticket sales, same meaning as events[].gross_cents."},"net_cents":{"type":"integer","description":"You keep, from the shared order money. Can be negative after refunds."},"refunds_cents":{"type":"integer"},"refunded_orders_count":{"type":"integer"},"passes_sold":{"type":"integer"},"day_tickets_sold":{"type":"integer"},"pass_comps":{"type":"integer"},"day_ticket_comps":{"type":"integer"},"programs":{"type":"array","items":{"type":"object","description":"A program inside a series: its own day tickets only. Never money, never a pass.","properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"The show's end time; null when none is set. Who's coming reads a show Live until it passes (ENG-2406)."},"has_day_tickets":{"type":"boolean","description":"False when the program sells no day ticket type (entry by pass)."},"day_tickets_sold":{"type":"integer"},"day_tickets_open":{"type":"integer"},"day_ticket_comps":{"type":"integer"}}}},"types":{"type":"array","items":{"type":"object","properties":{"tier_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["pass","day"]},"event_id":{"type":"string","format":"uuid","nullable":true,"description":"The program a day ticket is for. Always null for a pass."},"paid_sold":{"type":"integer"},"comps_issued":{"type":"integer"},"inventory_total":{"type":"integer"},"remaining":{"type":"integer","description":"The type's own unsold units (total - sold - reserved)."},"gross_cents":{"type":"integer"},"net_cents":{"type":"integer","description":"Type rows sum to the series net_cents."}}}},"show_fill":{"type":"array","description":"ENG-2406 Who's coming to each show: every show in the series with its pass places against its capacity. Day tickets stay on programs.","items":{"type":"object","required":["event_id","capacity","on_sale","pass_holders","excluded_from_passes","is_session"],"properties":{"event_id":{"type":"string","format":"uuid"},"capacity":{"type":"integer","nullable":true,"description":"The show's own capacity; null when none is set."},"on_sale":{"type":"integer","nullable":true,"description":"With no capacity: everything on sale for the show (day tickets, pass blocks, claim block), as the capacity ceiling counts it. Null when a capacity is set."},"pass_holders":{"type":"integer","description":"People with a pass place at the show (allocation summed over live pass tickets), claims included."},"excluded_from_passes":{"type":"boolean","description":"New buyers' passes skip the show; earlier holders keep their place."},"is_session":{"type":"boolean","description":"A claimable session: shown on the Sessions line, not as a show card."}}}},"door":{"type":"object","description":"Check-ins across the programs whose doors have opened. Expected at a program is its own live day tickets plus every live pass with an issued admit there; the pass host program plays no part. A program that has not opened is in neither number.","properties":{"status":{"type":"string","enum":["pre_door","available"]},"programs_count":{"type":"integer"},"programs_open_count":{"type":"integer"},"checked_in_count":{"type":"integer"},"expected_count":{"type":"integer"},"show_rate_bps":{"type":"integer","nullable":true,"description":"Null when nobody was expected."}}}}},"break_even":{"allOf":[{"$ref":"#/components/schemas/SalesBreakEven"}],"nullable":true,"description":"ENG-2408. A standalone event's or a series' break-even; null on the roll-up, for a show inside a series, and for a caller that never sees costs."},"lead_time":{"allOf":[{"$ref":"#/components/schemas/SalesLeadTime"}],"nullable":true},"tickets_per_order":{"allOf":[{"$ref":"#/components/schemas/TicketsPerOrderShare"}],"nullable":true},"last_year":{"allOf":[{"$ref":"#/components/schemas/SalesLastYear"}],"nullable":true},"event_counts":{"type":"object","nullable":true,"description":"Portfolio only. A series counts once, under each status one of its programs has.","properties":{"total":{"type":"integer"},"series_count":{"type":"integer"},"standalone_events_count":{"type":"integer"},"by_status":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"total":{"type":"integer"},"series_count":{"type":"integer"},"standalone_events_count":{"type":"integer"}}}},"by_filter":{"type":"object","description":"Events list tabs. A series counts once on each tab it has a program in; past is sold_out, completed and cancelled together.","properties":{"all":{"type":"integer"},"draft":{"type":"integer"},"on_sale":{"type":"integer"},"paused":{"type":"integer"},"past":{"type":"integer"}}}}}}}}}}}},"400":{"description":"Invalid id, or event_id combined with production_id."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Not found (event_not_found or production_not_found).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"502":{"description":"The dashboard could not be computed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tenants/{tenantId}/attendees":{"get":{"tags":["upgrades","tenants"],"summary":"List event attendees","operationId":"listTenantAttendees","description":"ENG-813 / ENG-795 / ENG-1643. Provide event_id XOR production_id. event_id is This-show (hosted tickets plus passes that admit that night). production_id is the whole run: every ticket on an order sold under the series (ENG-2332), plus tickets with no order on its programs; a pass holder appears once. upgraded=true returns only passes that completed a self-serve upgrade. Rows include upgrade_from_tier_name, upgrade_to_tier_name, upgrade_delta_cents, upgraded_at, upgrade_paid_by. CSV export of the same columns is GET /v1/tenants/{tenantId}/exports/attendees.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"production_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"upgraded","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Attendee page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"attendees":{"type":"array","items":{"type":"object","properties":{"upgraded":{"type":"boolean"},"upgrade_from_tier_name":{"type":"string","nullable":true},"upgrade_to_tier_name":{"type":"string","nullable":true},"upgrade_delta_cents":{"type":"integer","nullable":true},"upgraded_at":{"type":"string","format":"date-time","nullable":true},"upgrade_paid_by":{"type":"string","nullable":true}}}},"ticket_types":{"type":"array","description":"Every ticket type a guest in this scope holds, before filters and paging (the ticket-type filter's choices), sorted by name.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}}}}}}},"400":{"description":"event_id missing or upgraded not true/false."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient permissions. Needs guest_list.read on an organization-wide grant: organizer_admin, event_manager, or viewer (rows masked). Finance never reads the guest list (ENG-2559); finance plus viewer gets the viewer's masked rows. Checked before any parameter validation, so a refused caller gets 403, never 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tenants/{tenantId}/settlement/payouts/{stripePayoutId}/reconcile":{"get":{"tags":["settlement"],"summary":"Reconcile a Stripe payout batch to its orders","operationId":"getTenantSettlementPayoutReconcile","description":"ENG-221 T4: join connect_payout_charge_link (BalanceTransactions on payout.paid) to ticket_payments/orders vs payout amount. Tolerance documented as 1 cent. ENG-2751: one line per charge in the payout (an order's own charge, or a paid upgrade's own charge, found by its PaymentIntent), each read like a statement. `gross_cents` = everything the buyer was charged on that charge, tax included; `tax_cents`; `platform_fee_cents` = the AXYN fee Stripe took; `processing_fee_cents` = the card processing Stripe took; `refunds_cents` = refunds Stripe took out in this payout on that charge (a refund failure Stripe put back counts negative); `fee_refunds_cents` = AXYN fee Stripe returned in this payout; `adjustment_cents` = processing true-up (+ returned in this payout, - owed); ENG-2770: a refund or fee return whose charge paid out earlier gets a line with `charge_id` null, and one whose charge is no order of the tenant stays a `refunds` / `adjustments` composition line; `dispute_cents` / `dispute_fee_cents` = disputed money and dispute fees whose balance transactions this payout holds, net of reinstatements (an order whose charge paid out earlier gets a line with `charge_id` null); `net_cents` = gross - tax - platform fee - processing - refunds + fee refunds + adjustment - dispute - dispute fee. `axyn_*_cents` totals are the sums of the lines. `axyn_expected_payout_cents` = `axyn_net_cents` + `axyn_tax_cents`; `delta_cents` = payout - `axyn_expected_payout_cents`. ENG-2469: each line has `is_test` (AXYN marked the order as test); a test order stays in every line and total because its money is in the payout, and `axyn_test_orders_net_cents` is its share of `axyn_net_cents`.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"stripePayoutId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reconcile view."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Payout not found for tenant."},"502":{"description":"Reconcile load failed."}}}},"/v1/tenants/{tenantId}/settlement/payouts/{stripePayoutId}/reconcile.csv":{"get":{"tags":["settlement"],"summary":"CSV export of payout reconcile lines","operationId":"getTenantSettlementPayoutReconcileCsv","description":"ENG-221 T4: CSV of the same lines as getTenantSettlementPayoutReconcile, with the same meanings. Columns in order: stripe_payout_id, order_id, charge_id, transfer_id, gross_cents, platform_fee_cents, processing_fee_cents, refunds_cents, net_cents, stripe_payout_amount_cents, delta_cents, within_tolerance, charge_cents, tax_cents, application_fee_cents, fee_refunds_cents, venue_fee_cents, adjustment_cents, dispute_cents, dispute_fee_cents, is_test (ENG-2469: true on an order AXYN marked as test). New columns are only ever appended.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"stripePayoutId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV attachment.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Payout not found for tenant."},"502":{"description":"Reconcile load failed."}}}},"/v1/tenants/{tenantId}/settlement/payout-outlook":{"get":{"tags":["settlement"],"summary":"Where the organizer's payout money is and when it reaches the bank","operationId":"getTenantSettlementPayoutOutlook","description":"ENG-2357: staff JWT + settlement.read on the path tenant. Per series or standalone event: what is still in the Stripe balance, when the after-event payout job sends it (its own due date, waits and offsets), or why it waits. Approved tenants on Stripe's automatic schedule get the next payout day and the balance Stripe pays. Read-only. Viewer responses zero money fields and set viewer_masked. ENG-2376: on Stripe's schedule, available and pending come from one live Stripe balance read (5 s time limit, 60 s per-tenant cache); when Stripe errors or is slow, the stored balance snapshot answers with no clearing days. Each payout date carries its usual arrival (an estimate) or Stripe's own arrival_date. ENG-2375: event_id adds that event's own money as data.event.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"ENG-2375. Also answer this event's own money (its series' for a show in one) as data.event.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payout outlook.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PayoutOutlookView"}}}}}},"400":{"description":"tenantId or event_id is not a UUID."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"event_not_found: event_id is not an event of this tenant."},"502":{"description":"Payout outlook could not be loaded."}}}},"/v1/tenants/{tenantId}/settlement/payout-status":{"get":{"tags":["settlement"],"summary":"Get Organizer Admin payout / settlement status","operationId":"getTenantSettlementPayoutStatus","description":"ENG-221: staff JWT + settlement.read. Surfaces earned / in-transit / next / last / lifetime from Connect payout projections. Viewer responses zero money fields and set viewer_masked.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payout status view.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["payout_account","currency","available_cents","pending_balance_cents","in_transit_cents","lifetime_paid_cents","earned_to_date_cents","viewer_masked"],"properties":{"payout_account":{"type":"object","properties":{"status":{"type":"string"},"charges_enabled":{"type":"boolean"},"payouts_enabled":{"type":"boolean"},"payout_ready":{"type":"boolean"},"sell_ready":{"type":"boolean","description":"ENG-1567 S1. Stored sell-readiness from tenant_payout_account (no live Stripe probe)."},"sell_blocker":{"type":["string","null"],"description":"ENG-1567 S1. Null when sell_ready. Same codes as ConnectAccountView.sell_blocker."},"requirements_deadline":{"type":["object","null"],"description":"ENG-1948. The date Stripe turns charges off unless the information it asked for is provided. Null when charges are already off, nothing is due by a date, or a future requirement is more than 30 days away.","required":["due_by","stage","source","sales_at_risk"],"properties":{"due_by":{"type":"string","format":"date-time"},"stage":{"type":"string","enum":["first","seven_days","one_day"],"description":"seven_days and one_day: the deadline is within 7 days / 1 day."},"source":{"type":"string","enum":["currently_due","future_requirements"]},"sales_at_risk":{"type":"boolean","description":"True when an event on sale has tickets sold: its sales pause on due_by."}}},"stripe_paused_sales":{"type":"boolean","description":"ENG-1948. Stripe turned charges off on an account that sold before because it still wants information (status restricted)."}}},"currency":{"type":"string"},"available_cents":{"type":"integer"},"pending_balance_cents":{"type":"integer"},"in_transit_cents":{"type":"integer"},"lifetime_paid_cents":{"type":"integer"},"earned_to_date_cents":{"type":"integer","description":"ENG-2751: lifetime_paid_cents + in_transit_cents + pending_balance_cents + available_cents. On a Stripe schedule the balance is the same live read the payout outlook uses."},"next_payout":{"nullable":true,"type":"object"},"last_payout":{"nullable":true,"type":"object"},"latest_failed_payout":{"nullable":true,"type":"object","description":"Most recent payout.failed projection with Stripe failure_code/message (OD10.8)."},"holds":{"type":"array","description":"Active Stripe-imposed holds/reserves with reason + optional expected_release_at (OD10.6)."},"fix_payout_method":{"type":"object","description":"Affordance pointing at existing Connect account route to update payout method.","properties":{"connect_account_path":{"type":"string"}}},"viewer_masked":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"502":{"description":"Payout status load failed."}}}},"/v1/staff/invitations/{token}/accept":{"post":{"tags":["tenants"],"summary":"Accept a tenant staff invitation","operationId":"acceptStaffInvitation","description":"The signed-in user accepts the invitation named by its emailed token. The JWT email must match the invited email. Repeating an accept the caller already holds returns already_granted: true.","security":[{"bearerAuth":[]}],"parameters":[{"name":"token","in":"path","required":true,"description":"Invitation token from the invite email.","schema":{"type":"string"}}],"responses":{"200":{"description":"Invitation accepted; the caller is now tenant staff.","content":{"application/json":{"schema":{"type":"object","required":["success","staff_id","tenant_id","role","event_id"],"properties":{"success":{"type":"boolean","enum":[true]},"staff_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"role":{"type":"string"},"event_id":{"type":["string","null"],"format":"uuid","description":"Set when the grant is scoped to one event."},"already_granted":{"type":"boolean","description":"Present (true) when the caller already held this grant."}}}}}},"400":{"description":"Malformed token, or the invitation is expired, revoked, already accepted, or addressed to another email.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["invalid_request","expired","revoked","already_accepted","email_mismatch"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No invitation has this token.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["not_found"]}}}}}},"500":{"description":"Database failure.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["db_error"]}}}}}}}}},"/v1/webhooks/ethoca":{"post":{"tags":["webhooks"],"summary":"Ethoca pre-chargeback alert receiver","operationId":"ethocaWebhook","description":"M25: raw-body endpoint verified by an HMAC-SHA256 hex digest of the body in x-ethoca-signature. Never accepts an unsigned alert. A durable alert whose decision was deferred acks 200 with deferred: true (the prevention sweeper retries it); a non-durable ingest answers 503 so Ethoca retries.","security":[],"parameters":[{"name":"x-ethoca-signature","in":"header","required":true,"description":"Hex HMAC-SHA256 of the raw body.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["alert_id"],"properties":{"alert_id":{"type":"string"},"charge_id":{"type":["string","null"]},"payment_intent_id":{"type":["string","null"]},"amount_cents":{"type":["integer","null"]},"reason":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Alert recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EthocaWebhookAck"}}}},"400":{"description":"Missing or invalid signature, or a body without alert_id.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["invalid_signature","invalid_payload"]}}}}}},"503":{"description":"Webhook unconfigured (success:false, error webhook_disabled), or the alert was not stored durably (received:false, deferred:true, error ingest_not_durable | pipeline_exception); Ethoca retries.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["webhook_disabled"]}}},{"allOf":[{"$ref":"#/components/schemas/EthocaWebhookAck"},{"type":"object","properties":{"error":{"type":"string","enum":["ingest_not_durable","pipeline_exception"]}}}]}]}}}}}}},"/v1/webhooks/stripe":{"post":{"tags":["webhooks"],"summary":"Stripe webhook receiver","operationId":"stripeWebhook","description":"Raw-body endpoint verified by the Stripe-Signature header. Handles payment_intent.succeeded/payment_failed/processing, charge.refunded, charge.dispute.*, account.updated.","security":[],"parameters":[{"name":"Stripe-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Raw Stripe Event payload."}}}},"responses":{"200":{"description":"Received (may include duplicate:true).","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"duplicate":{"type":"boolean"}}}}}},"400":{"description":"Signature verification failure (text/plain: 'Webhook Error: ...')."},"500":{"description":"Processing/persistence failure."},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/v1/webhooks/twilio":{"post":{"tags":["webhooks"],"summary":"Twilio message status callback","operationId":"twilioStatusWebhook","description":"ENG-2869: form-encoded status callback for one text. The MessageSid is matched to a text row, the row binds the organizer, and the X-Twilio-Signature is checked with that organizer's sub-account (the AccountSid in the callback must be that sub-account). The row is then written from the provider's Message resource: status, error code, segments and price.","security":[],"parameters":[{"name":"X-Twilio-Signature","in":"header","required":true,"description":"Base64 HMAC-SHA1 of the callback URL and the sorted form fields, keyed by the sub-account auth token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","description":"Twilio's flat status-callback form fields (MessageSid, AccountSid, MessageStatus, ErrorCode, ...), signed as posted."}}}},"responses":{"204":{"description":"Recorded from the provider's Message resource."},"400":{"description":"Not a Twilio status callback (no MessageSid or AccountSid).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["invalid_payload"]}}}}}},"403":{"description":"The MessageSid names no text AXYN sent, the callback names another account, or the signature does not verify with the organizer's sub-account. Every case answers the same body.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["invalid_signature"]}}}}}},"503":{"description":"SMS provider or public API base URL unconfigured.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["webhook_disabled"]}}}}}}}}},"/v1/tickets/{ticketId}/void":{"post":{"tags":["ticket-lifecycle"],"summary":"Void a ticket (organizer)","operationId":"voidTicket","description":"Organizer-side terminal void of an issued ticket. Idempotent. Restricted to {organizer_admin, event_manager}. ENG-1723: a paid ticket returns to inventory and its reserved seat is released in the same transaction; the response lists where each seat went.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["void_reason"],"properties":{"void_reason":{"type":"string","minLength":1,"maxLength":1000},"seat_destination":{"type":"string","enum":["default","open_sale","house_hold","off_sale"],"default":"default","description":"ENG-1723. Where a reserved seat goes when this ticket ends. `default` returns it where it came from (its house hold, else open sale). A cancelled event or an already-scanned ticket always sends the seat off sale."},"seat_house_hold_id":{"type":"string","format":"uuid","description":"Required when seat_destination is house_hold. Must be a hold on the same event."},"seat_off_sale_note":{"type":"string","maxLength":200,"description":"Optional staff note when seat_destination is off_sale."},"confirm_door_risk":{"type":"boolean","default":false,"description":"Put the seat back on sale even though an offline door list issued in the last 12 hours may still admit the old barcode. Without it such a seat stays off sale until every door list refreshes or expires."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"released_seats":{"type":"array","items":{"$ref":"#/components/schemas/ReleasedSeat"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"seat_house_hold_not_found: the chosen house hold is not on this ticket's event. Nothing changed."}}}},"/v1/tickets/{ticketId}/voucher-swap":{"post":{"tags":["ticket-lifecycle"],"summary":"Swap a paid ticket for an issued voucher (organizer)","operationId":"ticketVoucherSwap","description":"M28b — swap a paid ticket for an active voucher of matching face value. Single writer of ticket.status → voided + voucher issuance in one transaction.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1},"voucher_expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ticket_id":{"type":"string","format":"uuid"},"voucher_id":{"type":"string","format":"uuid"},"voucher_code":{"type":"string"},"face_value_cents":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tenants/{tenantId}/tickets/{ticketId}/return-to-hold":{"post":{"tags":["ticket-lifecycle"],"summary":"Return an unused complimentary ticket to Held (organizer)","operationId":"ticketCompReturnToHold","description":"Void a hold-issued unused comp and add that seat back to Remaining Held. Does not change generic ticket void. Paid, redeemed, and exchanged tickets are refused.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_reason"],"properties":{"return_reason":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Returned or already returned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid"},"hold_id":{"type":"string","format":"uuid"},"remaining_held":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tenants/{tenantId}/tickets/{ticketId}/seat-release-preview":{"get":{"tags":["ticket-lifecycle"],"summary":"Preview seats a void frees","operationId":"previewTicketSeatRelease","description":"ENG-1723. Read-only. Each reserved seat voiding this ticket would free, its label and ticket type, and where it goes by default (same rule as the void). Nothing moves.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Seats and their default destinations.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatReleasePreview"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Unable to load the seats."}}}},"/v1/tenants/{tenantId}/refund-requests":{"post":{"tags":["refunds"],"summary":"Refund chosen tickets of an order","operationId":"refundTenantOrderTickets","description":"ENG-3040. An owner or event manager refunds chosen tickets of an order. Each ticket becomes one refund request for the amount AXYN's voluntary refund rules give (fees kept), approved at once through the same step a buyer's request goes through; the refund worker then returns the money to how the buyer paid, or records a cash-at-the-door order as paid back in cash. A second call for a ticket already refunded reports it `refunded` again and moves no money. Seat fields as on the decision. Tenant comes from the path, never the body.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id","ticket_ids","reason"],"properties":{"order_id":{"type":"string","format":"uuid"},"ticket_ids":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","format":"uuid"}},"reason":{"type":"string","minLength":1,"maxLength":2000},"seat_destination":{"type":"string","enum":["default","open_sale","house_hold","off_sale"],"default":"default"},"seat_house_hold_id":{"type":"string","format":"uuid"},"seat_off_sale_note":{"type":"string","maxLength":200},"confirm_door_risk":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Each chosen ticket's outcome.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["result_code","tickets"],"properties":{"result_code":{"type":"string","enum":["refunds_started"]},"tickets":{"type":"array","items":{"type":"object","required":["ticket_id","result","refund_request_id","amount_cents"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"result":{"type":"string","description":"`refunded`, or why this ticket was not: a refund ineligibility code (`ticket_redeemed`, `ticket_transferred`, `ticket_not_live`, …), a decision result code, or `refund_failed` when this ticket hit an error (read the order's refund requests to see whether its approval went through; the other tickets are unaffected)."},"refund_request_id":{"type":"string","format":"uuid","nullable":true},"amount_cents":{"type":"integer","nullable":true}}}}}}}}}}},"400":{"description":"Invalid body."},"401":{"description":"Not signed in."},"403":{"description":"The role cannot refund (`refund_request.decide`)."},"404":{"description":"`order_not_found` in this organization."}}}},"/v1/tenants/{tenantId}/refund-requests/{requestId}/decision":{"post":{"tags":["refunds"],"summary":"Approve or reject a refund request","operationId":"decideTenantRefundRequest","description":"M46o. Staff decide one pending buyer refund request. Approve may lower the amount; a whole-order approve below the remaining amount keeps the tickets valid. ENG-1723: on approve, the refunded tickets' reserved seats are released right after the money decision (seat fields as on void) and listed in `released_seats`. Tenant comes from the path, never the body.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]},"approved_amount_cents":{"type":"integer","minimum":0,"description":"Approve only. Defaults to the requested amount."},"reviewer_note":{"type":"string","minLength":1,"maxLength":2000,"description":"Required to reject."},"seat_destination":{"type":"string","enum":["default","open_sale","house_hold","off_sale"],"default":"default","description":"ENG-1723. Where a reserved seat goes when this ticket ends. `default` returns it where it came from (its house hold, else open sale). A cancelled event or an already-scanned ticket always sends the seat off sale."},"seat_house_hold_id":{"type":"string","format":"uuid","description":"Required when seat_destination is house_hold. Must be a hold on the same event."},"seat_off_sale_note":{"type":"string","maxLength":200,"description":"Optional staff note when seat_destination is off_sale."},"confirm_door_risk":{"type":"boolean","default":false,"description":"Put the seat back on sale even though an offline door list issued in the last 12 hours may still admit the old barcode. Without it such a seat stays off sale until every door list refreshes or expires."}}}}}},"responses":{"200":{"description":"Decided.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["result_code"],"properties":{"result_code":{"type":"string"},"current_status":{"type":"string"},"decision":{"type":"string","enum":["approve","reject"]},"refund_request":{"type":"object","additionalProperties":true},"released_seats":{"type":"array","items":{"$ref":"#/components/schemas/ReleasedSeat"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"seat_house_hold_not_found: the chosen house hold is not on the refunded seats' event. Nothing changed; the request stays pending."}}}},"/v1/tenants/{tenantId}/refund-requests/{requestId}/seat-release-preview":{"get":{"tags":["ticket-lifecycle"],"summary":"Preview seats a refund frees","operationId":"previewRefundRequestSeatRelease","description":"ENG-1723. Read-only. Each reserved seat approving this refund request would free (its ticket, or the order's live tickets) and where it goes by default. A whole-order approve below the remaining amount refunds no tickets, so no seats move. Nothing moves.","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Seats and their default destinations.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeatReleasePreview"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Unable to load the seats."}}}},"/v1/tenants/{tenantId}/tickets/{ticketId}/upgrade-invites":{"post":{"tags":["upgrades","tenants"],"summary":"Create a 72h guest upgrade link","operationId":"createStaffUpgradeInvite","description":"ENG-801. Bound to ticket_id + tenant. Does not remint the Live Pass. Optional target_tier_id skips the picker. send_email emails the guest.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_tier_id":{"type":"string","format":"uuid"},"send_email":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Link minted; email skipped because the guest has no email."},"201":{"description":"Invite created."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/{ticketId}/comp-exchange":{"post":{"tags":["ticket-lifecycle"],"summary":"Exchange a paid ticket for a comp on another tier (organizer)","operationId":"ticketCompExchange","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_tier_id","reason"],"properties":{"target_tier_id":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"source_ticket_id":{"type":"string","format":"uuid"},"new_ticket_id":{"type":"string","format":"uuid"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/{ticketId}/reissue":{"post":{"tags":["ticket-lifecycle"],"summary":"Reissue a paid ticket (organizer)","operationId":"ticketReissue","description":"Void the source paid ticket and mint a replacement ticket on the target tier in one transaction. The response identifies the reissue resource and never returns a stored ticket QR.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reissue_reason","target_tier_id"],"properties":{"reissue_reason":{"type":"string","minLength":1},"target_tier_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ticket_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid","nullable":true},"result_code":{"type":"string"},"reissue":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"source_ticket_id":{"type":"string","format":"uuid","nullable":true},"new_ticket_id":{"type":"string","format":"uuid","nullable":true},"source_tier_id":{"type":"string","format":"uuid","nullable":true},"target_tier_id":{"type":"string","format":"uuid","nullable":true},"reissue_reason":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid","nullable":true}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tickets/{ticketId}/move-tier":{"post":{"tags":["ticket-lifecycle"],"summary":"Move a pass to another tier or another show of its series in place (organizer)","operationId":"ticketMoveTier","description":"Move a live pass to another tier without replacing it. The ticket keeps its id, ticket_number, qr_code and pass link, so the guest's existing link simply starts reading the new tier and nothing is re-sent. Tier inventory rebalances (source sold minus one, target sold plus one) and the change is recorded in ticket_tier_moves, because a tier-only update fires no status audit trigger. Refuses seated passes (ticket_is_seated), section-linked target tiers that draw on the area pool (target_tier_is_section_linked), non-active passes, and targets with no availability.\n\nChange show: when the target tier is on another show of the same series, at the same price and currency, the pass moves to that show (result_code `ticket_show_moved`). `ticket_ids` names other tickets of the same order and ticket type that move with it, in one transaction. Answers to the old show's questions move to the new show's question with the same wording. Refuses a started or closed show (`target_event_not_open`), another series (`target_event_not_in_series`), another price (`target_price_differs`), too few tickets left (`target_tier_short`), a full show (`target_show_full`), and tickets that were scanned, transferred, refunded or are being refunded (`ticket_not_movable`, `ticket_has_history`, `order_has_refund_request`). An event-scoped grant may move only onto a show it manages (403 `target_tier_outside_event_scope`). `notify_guest: true` emails the buyer the new day and time.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_tier_id","move_reason"],"properties":{"target_tier_id":{"type":"string","format":"uuid"},"move_reason":{"type":"string","minLength":1},"ticket_ids":{"type":"array","maxItems":50,"description":"Change show only: other tickets of the same order and ticket type that move with this one.","items":{"type":"string","format":"uuid"}},"notify_guest":{"type":"boolean","description":"Change show only: email the buyer the new day and time."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid","nullable":true},"tenant_id":{"type":"string","format":"uuid","nullable":true},"source_tier_id":{"type":"string","format":"uuid","nullable":true},"target_tier_id":{"type":"string","format":"uuid","nullable":true},"source_price_cents":{"type":"integer","nullable":true},"target_price_cents":{"type":"integer","nullable":true},"move_reason":{"type":"string","nullable":true},"ticket_ids":{"type":"array","description":"Change show: the tickets that moved.","items":{"type":"string","format":"uuid"}},"source_event_id":{"type":"string","format":"uuid","nullable":true},"target_event_id":{"type":"string","format":"uuid","nullable":true},"target_starts_at":{"type":"string","format":"date-time","nullable":true},"guest_notified":{"type":"boolean","description":"Change show: the email with the new day and time was queued for the buyer."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/{ticketId}/supersede":{"post":{"tags":["ticket-lifecycle"],"summary":"Retire a pass into the pass that replaced it (organizer)","operationId":"ticketSupersede","description":"Void the source pass (when it is not already voided) and point it at into_ticket_id in one transaction, so the source pass keeps admitting the target at the door instead of being denied as revoked. Both passes must belong to the same tenant, the same event, and the same holder. Replaying the same pair echoes the existing pointer and changes nothing. A source ticket with a ticket-scoped refund request still open (pending, or approved and not yet executed) is refused with 409 and data.result_code ticket_refund_request_open (data.refund_request_id names it); decide the refund first. A voided source whose order already had an order-level refund approved is refused with 409 and data.result_code ticket_order_refunded when the target is on another order, since its share may already be back with the buyer. Refusals carry a human-readable error sentence.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["into_ticket_id","supersede_reason"],"properties":{"into_ticket_id":{"type":"string","format":"uuid"},"supersede_reason":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid","nullable":true},"tenant_id":{"type":"string","format":"uuid","nullable":true},"superseded_by_ticket_id":{"type":"string","format":"uuid","nullable":true},"previous_status":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"supersede_reason":{"type":"string","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/{ticketId}/transfer-offers":{"post":{"tags":["transfers"],"summary":"Create an outgoing ticket transfer offer","operationId":"createTicketTransferOffer","description":"Issue a transfer offer for a ticket the buyer holds. Requires buyer JWT; a tenant API key is optional and, when sent, must match the ticket's tenant (the tenant is derived from the ticket, so first-party clients omit it). The JWT user must be the ticket's current holder (purchaser until a completed transfer, attendee when set); anyone else gets the same opaque 404 ticket_not_found as an unknown ticket. A dispute-held ticket or one with a pending / approved-not-processed refund answers 409 ticket_not_transferable with data.actual_status dispute_hold / refund_pending. Recipient claims via /v1/ticket-transfer-claims/{tokenOrShareCode}. Raw claim token is returned once on 201; idempotent replay returns empty token.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient_email"],"properties":{"recipient_email":{"type":"string","format":"email"},"ttl_seconds":{"type":"integer","minimum":1,"description":"Optional offer lifetime in seconds (bounded server-side)."}}}}}},"responses":{"200":{"description":"Idempotent: offer already pending for this ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketTransferOfferIssuedResponse"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketTransferOfferIssuedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tickets/{ticketId}/transfer-offers/revoke":{"post":{"tags":["transfers"],"summary":"Revoke a pending outgoing transfer offer","operationId":"revokeTicketTransferOffer","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Revoked or already revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"token_id":{"type":"string","format":"uuid","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"revoke_reason":{"type":"string","nullable":true},"claimed_at":{"type":"string","format":"date-time","nullable":true},"claimed_by_user_id":{"type":"string","format":"uuid","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"description":"Revoke the pending transfer offer for a ticket the buyer holds. Requires buyer JWT; a tenant API key is optional and, when sent, must match the ticket's tenant. Only the ticket's current holder may revoke; anyone else gets the opaque 404 ticket_transfer_offer_not_found. Optional reason."}},"/v1/ticket-transfer-claims/{token}":{"get":{"tags":["transfers","public"],"summary":"Preview a transfer accept shell","operationId":"previewTicketTransferClaim","description":"Public accept-shell preview (event + venue brand). Possession of the transfer claim token or share code is the credential; no buyer JWT.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque transfer claim token or share code.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event":{"description":"What the ticket on offer is for. Null when its name or start could not be read, and for a pass with no valid date.","type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"timezone":{"type":["string","null"],"description":"The IANA zone `starts_at` and the pass's dates read in: the venue's, else the event's, else the organization's default. Null when none is set."}}},"tenant":{"oneOf":[{"$ref":"#/components/schemas/BuyerTenantBrand"},{"type":"null"}]},"series":{"description":"ENG-2337. The series the ticket belongs to and whether its holders see the lineup. Null for a standalone event, or when it could not be read.","oneOf":[{"$ref":"#/components/schemas/HeldTicketSeries"},{"type":"null"}]},"pass":{"description":"ENG-2338. Only when the ticket's type is a pass. A pass is dated by the programs it admits: `event.starts_at` is `pass.valid_from`, and `event` is null when the pass has no valid date (never its host program's start).","oneOf":[{"$ref":"#/components/schemas/HeldTicketPass"},{"type":"null"}]},"attendee_name_required":{"type":"boolean","description":"ENG-733. True when the ticket needs the new holder's name: its event requires attendee details, or the buyer named this ticket's holder at checkout. The claim must then send both `guest_first_name` and `guest_last_name`."}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["transfers","public"],"summary":"Claim an incoming ticket transfer","operationId":"claimTicketTransfer","description":"Public guest claim. Possession of the transfer claim token or share code is the credential for the FIRST claim only. Optional guest_first_name / guest_last_name for Live Pass display. Both are required when the offer preview reports attendee_name_required (the event requires a name for every ticket, or the buyer named this ticket's holder at checkout); a claim without them is refused with 400 attendee_name_required and nothing is claimed. A name sent on a first claim replaces both parts of the previous holder's name (a part left out is cleared). First claim success includes pass_bearer for the recipient live pass. Reopening an already-claimed link is refused (409 ticket_transfer_offer_already_claimed, nothing reminted) unless it is the ticket's latest completed transfer on an active ticket; then the fresh pass is returned only when device_key_hash matches a Live Pass device bound after the claim, otherwise it is emailed to the recipient and pass_bearer is null (recovery_email_sent reports delivery).","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque transfer claim token or share code.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"guest_first_name":{"type":"string","maxLength":80,"description":"Optional display name (ENG-475). Required when the offer preview reports attendee_name_required (ENG-733)."},"guest_last_name":{"type":"string","maxLength":80,"description":"Optional display name (ENG-475). Required when the offer preview reports attendee_name_required (ENG-733)."},"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Optional Live Pass device key hash of this browser. Lets the recipient reopen an already-claimed link on a device already bound to the pass."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid"},"qr_issued_at":{"type":"string","format":"date-time","nullable":true},"claimed_at":{"type":"string","format":"date-time","nullable":true},"pass_bearer":{"type":"string","nullable":true,"description":"Fresh ticket-url bearer for the recipient live pass. Null on a reopen that was not presented from the recipient's bound Live Pass device (the pass was emailed instead)."},"recovery_email_sent":{"type":"boolean","description":"Present on an emailed reopen: whether the fresh Live Pass email was sent to the recipient."}}}}}}}},"400":{"description":"attendee_name_required: the ticket needs the new holder's name (the event requires a name for every ticket, or the buyer named this ticket's holder at checkout) and the claim did not send both guest_first_name and guest_last_name. Nothing is claimed. Ask for the name and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"ticket_transfer_offer_already_claimed: the link was already claimed and the ticket has since moved on (or is no longer active). No credential is minted and the current holder's pass is untouched."},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Claim remint or downstream failure"}}}},"/v1/scanner/disputes":{"post":{"tags":["scanning"],"summary":"Open a scanner dispute","operationId":"createScannerDispute","description":"A door-staff scanner opens a dispute when a ticket presented in person cannot be admitted (already-scanned, damaged QR, identity mismatch).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticket_id","reason_code"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"reason_code":{"type":"string"},"notes":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dispute_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/scanner/disputes/{disputeId}/resolve":{"post":{"tags":["scanning"],"summary":"Resolve a scanner dispute","operationId":"resolveScannerDispute","security":[{"bearerAuth":[]}],"parameters":[{"name":"disputeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["resolution"],"properties":{"resolution":{"type":"string","enum":["admit","reject","refund"]},"notes":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dispute_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/scanner/walk-up-sale":{"post":{"tags":["scanning"],"summary":"Sell a walk-up ticket at the door","operationId":"scannerCreateWalkUpSale","description":"ENG-246 — staff JWT sells against live shared inventory (same rpc_order_create_atomic as online checkout). Requires Idempotency-Key. Purchaser is the guest; staff JWT is the actor only. Cash sales return a cash_arrangement and complete via POST /v1/scanner/cash-collected.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TenantIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_id","venue_event_id","payment_method","purchaser_name","purchaser_email","lines"],"properties":{"venue_id":{"type":"string","format":"uuid"},"venue_event_id":{"type":"string","format":"uuid"},"payment_method":{"type":"string","enum":["card","apple_pay","google_pay","cash_at_entry"]},"purchaser_name":{"type":"string","minLength":2,"maxLength":120},"purchaser_email":{"type":"string","format":"email"},"purchaser_phone":{"type":"string","nullable":true,"description":"Send it with its + and country code (the door app's country-code picker does). Stored in E.164 when it reads as one, else exactly as typed; the sale is never refused for it and the venue's country is never assumed."},"lines":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/OrderLineInput"}},"coupon_codes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Idempotent replay of an existing walk-up order"},"201":{"description":"Walk-up order reserved"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"walk_up_not_enabled or event not sellable"}}}},"/v1/scanner/cash-collected":{"post":{"tags":["scanning"],"summary":"Record cash-at-entry collection at the door","operationId":"scannerRecordCashCollection","description":"M22c — flips the cash-at-entry arrangement from pending → collected once the door collects the expected amount.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id","amount_cents"],"properties":{"order_id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer","minimum":0},"currency":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/events/{eventId}/cover":{"post":{"tags":["event-lifecycle"],"summary":"Upload an event cover image (API key or staff JWT + x-tenant-id)","operationId":"uploadEventCover","description":"ENG-501 — store a JPEG/PNG/WebP (≤5 MiB) in AXYN object storage and write event.hero_image_url in the same request. Magic-byte sniff; tenant from the API key / staff context. Headless partners with their own CDN may PATCH hero_image_url instead.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP. 5 MiB or smaller."}}}}}},"responses":{"200":{"description":"Cover stored and hero_image_url updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"hero_image_url":{"type":"string","format":"uri"},"cover_crops":{"$ref":"#/components/schemas/CoverCrops"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"description":"Cover object store is not configured or put failed"}}}},"/v1/events/{eventId}/view-stills":{"get":{"tags":["catalog"],"summary":"List view stills for a reserved-seat event","operationId":"listEventViewStills","description":"ENG-1153 — organizer list. Tenant from the API key. GA returns 422 layout_not_reserved_seat.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"View stills for this event","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ViewStill"}}}}}}},"422":{"description":"layout_not_reserved_seat"}}},"post":{"tags":["catalog"],"summary":"Host or link a view still","operationId":"createEventViewStill","description":"ENG-1153 — multipart JPEG/PNG/WebP (≤5 MiB) stores a hosted still under event-covers/view-stills/. JSON { url, coverage_label? } links an https URL. Default coverage: Shared view for this section, not your exact chair. Missing stills never block pay.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP. 5 MiB or smaller."}}}},"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https image URL. http and data: are refused."},"coverage_label":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"Still created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ViewStill"}}}}}},"400":{"description":"invalid_image or file_too_large"},"422":{"description":"invalid_url, coverage_too_long, or layout_not_reserved_seat"},"503":{"description":"view_still_storage_unavailable"}}}},"/v1/events/{eventId}/view-stills/{stillId}":{"patch":{"tags":["catalog"],"summary":"Update a view still coverage line","operationId":"patchEventViewStill","description":"ENG-1153 — coverage_label only, max 120. Other tenant or missing still is 404 with no extra hint.","security":[{"bearerAuth":[]},{"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"stillId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["coverage_label"],"properties":{"coverage_label":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"Updated still","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ViewStill"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"coverage_too_long or layout_not_reserved_seat"}}},"delete":{"tags":["catalog"],"summary":"Delete a view still and clear assignments","operationId":"deleteEventViewStill","description":"ENG-1153 — clears seat and section FKs, then deletes the row. Other tenant 404 with no extra hint.","security":[{"bearerAuth":[]},{"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"stillId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/preview-tokens":{"post":{"tags":["event-lifecycle"],"summary":"Issue a draft preview token (API key or staff JWT + x-tenant-id)","operationId":"createEventPreviewToken","description":"M13 (OD2.5) — issue a 32-byte bearer token that lets a non-account collaborator preview a draft event. Rate-limited on the public preview endpoint.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_hours":{"type":"integer","minimum":1,"maximum":720},"label":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/preview-tokens/revoke":{"post":{"tags":["event-lifecycle"],"summary":"Revoke a draft-preview token","operationId":"revokeEventPreviewToken","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_id"],"properties":{"token_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revoked_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/photo-urls":{"post":{"tags":["photos"],"summary":"Register event photo URLs (staff JWT required for attribution; dual-auth gate)","operationId":"createEventPhotoUploadUrl","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content_type","byte_size"],"properties":{"content_type":{"type":"string"},"byte_size":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"upload_url":{"type":"string"},"object_key":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/cancel":{"post":{"tags":["event-lifecycle"],"summary":"Cancel an event (staff JWT required for attribution; dual-auth gate)","operationId":"cancelEvent","description":"M46h / T-136 — organizer force-majeure cancellation. Dual-auth gate: API key `catalog:write` or staff JWT `event.cancel` + `x-tenant-id`. Declaration still requires a staff JWT for `declared_by` attribution. Pins HF-028 SLA targets and flips event.status to cancelled.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["force_majeure_reason"],"properties":{"force_majeure_reason":{"type":"string","minLength":1,"maxLength":2000},"cancellation_scope":{"type":"string","enum":["full","partial"],"default":"full"},"affected_day_dates":{"type":"array","items":{"type":"string","format":"date"},"nullable":true,"description":"Required when cancellation_scope=partial; omit when full."}}}}}},"responses":{"200":{"description":"Already declared (idempotent)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"cancellation_event_id":{"type":"string","format":"uuid","nullable":true},"event_id":{"type":"string","format":"uuid","nullable":true},"tenant_id":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","nullable":true},"comms_sla_target_at":{"type":"string","format":"date-time","nullable":true},"refund_sla_target_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"201":{"description":"Cancellation declared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"cancellation_event_id":{"type":"string","format":"uuid","nullable":true},"event_id":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/events/{eventId}/views":{"post":{"tags":["public","partner"],"summary":"Ingest a de-identified event view fact (ENG-500)","operationId":"postEventViewFact","description":"First-party Sales impressions beacon. Tenant is derived from the event. Optional tenant API key must match when present (ENG-635: not required for headless pixel). headless_api is rejected unless the event has partner_commerce_pixel_enabled set (ENG-623 commerce pixel). Every other surface (Web SDK embed, hosted shop) is rejected unless the event has partner_embed_analytics_enabled set (ENG-2175, default off). Catalog GET does not create facts. A program inside a series carries its series' switches, and its fact counts toward the series (ENG-2307).","security":[{},{"tenantApiKey":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_key"],"properties":{"session_key":{"type":"string","minLength":8,"maxLength":128,"description":"Opaque anonymous session id (never email/PII)"},"checkout_host":{"type":"string","nullable":true},"checkout_surface":{"type":"string","enum":["axyn_hosted","axyn_shop","partner_embed","partner_headless","unknown"]},"checkout_integration":{"type":"string","enum":["axyn_web","web_sdk","mobile_sdk","headless_api","unknown"],"description":"headless_api is only accepted when the event has partner_commerce_pixel_enabled set (ENG-623); otherwise the request is rejected"},"funnel_step":{"type":"string","enum":["view","unavailable","tier_select","cart","details","checkout_start","payment_open","payment_failed","hold_expired","promo_tried"],"description":"Optional funnel step; omitted means view. unavailable: the page was shown sold out or not on sale. tier_select / cart: chose tickets. details: buyer details entered. checkout_start: the order exists. payment_open / payment_failed: the payment step. hold_expired: the checkout timer ran out. promo_tried: a code was entered. Paid is never a step: it comes from orders. The commerce pixel sends each step by the command of the same name. A one-shot step already stored for the journey answers 200 with duplicate: true."},"step_outcome":{"type":"string","enum":["sold_out","not_on_sale","sales_ended","declined","verification","other","worked","did_not_work"],"description":"Coarse outcome (ENG-2311). unavailable: sold_out | not_on_sale | sales_ended. payment_failed: declined | verification | other. promo_tried: worked | did_not_work. An outcome the step cannot carry is ignored. Never send a promo code or anything the buyer typed."},"time_zone":{"type":"string","maxLength":64,"description":"The browser's time zone name (for example America/Chicago). AXYN reads a country from it, and a state or province where one zone is one state, then discards it. Approximate. An unknown zone is ignored."},"device_class":{"type":"string","enum":["mobile","desktop"],"description":"Phone or computer (ENG-2311). Anything else is ignored."},"referrer_host":{"type":"string","maxLength":255,"description":"Host name of the site that sent the visitor (ENG-2311). Host only: a path or full address is ignored."},"landing_path":{"type":"string","maxLength":1024,"description":"Path and query string of the page the visit started on (ENG-2314), where a link carries its campaign. Scrubbed before storage: no fragment, no value on a parameter that names identity or a secret, no value that looks like an email or a written phone number."},"utm_source":{"type":"string","maxLength":128,"description":"Campaign source (ENG-2314). Read from landing_path when not sent. Stored lower-case."},"utm_medium":{"type":"string","maxLength":128},"utm_campaign":{"type":"string","maxLength":128},"visitor_key":{"type":"string","minLength":8,"maxLength":128,"description":"Opaque first-party id that lets a journey span visits for up to 30 days (ENG-2319). One per organizer. Never email-derived."},"order_id":{"type":"string","format":"uuid","description":"Partner commerce pixel only (ENG-2470): on checkout_start or payment_open, the id of the order the partner's server just created. AXYN links that order to this journey when the order is this organizer's, for this event or series, created in the last hour and not already linked. Used for the link only and never stored on the funnel record. Ignored on other steps and surfaces; a missing or unknown id never refuses the step."},"items":{"type":"array","maxItems":20,"description":"The ticket or pass types in hand at this step (ENG-2310). Priced by AXYN from the catalog; a price sent here is ignored. An item that is not a ticket type of this event or series, or has a quantity outside 1 to 100, is dropped and the step still counts.","items":{"type":"object","required":["ticket_tier_id","quantity"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":100}}}}}}}}},"responses":{"200":{"description":"Already stored: this one-shot step was recorded for the journey before (a reload, a retry, a second copy of the pixel). Nothing new was written.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","nullable":true},"duplicate":{"type":"boolean"}}}}}}}},"201":{"description":"View fact stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"202":{"description":"Accepted and dropped: funnel ingest was at its ceiling (ENG-2317). Nothing was stored; do not retry. A beacon never queues behind, or competes with, an order."},"204":{"description":"Funnel analytics is switched off for the platform (ENG-2317). Nothing was read or stored."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation failed, pixel_disabled when headless ingest is off for the event, or embed_analytics_disabled when analytics on partner embeds is off for the event (ENG-2175)"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/productions/{productionId}/views":{"post":{"tags":["public","partner"],"summary":"Ingest a de-identified funnel fact for a series (ENG-2307)","operationId":"postSeriesViewFact","description":"The series form of POST /v1/events/{eventId}/views: the same body, gates and errors, with the organizer's two opt-ins read from the series (partner_embed_analytics_enabled, partner_commerce_pixel_enabled; both default off). A series has its own checkout funnel; a program inside it has none of its own. Tenant is derived from the series. An unknown id, an event id and another organizer's series all return 404 series_not_found.","security":[{},{"tenantApiKey":[]}],"parameters":[{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_key"],"properties":{"session_key":{"type":"string","minLength":8,"maxLength":128,"description":"Opaque anonymous session id (never email/PII)"},"checkout_host":{"type":"string","nullable":true},"checkout_surface":{"type":"string","enum":["axyn_hosted","axyn_shop","partner_embed","partner_headless","unknown"]},"checkout_integration":{"type":"string","enum":["axyn_web","web_sdk","mobile_sdk","headless_api","unknown"],"description":"headless_api is only accepted when the event has partner_commerce_pixel_enabled set (ENG-623); otherwise the request is rejected"},"funnel_step":{"type":"string","enum":["view","unavailable","tier_select","cart","details","checkout_start","payment_open","payment_failed","hold_expired","promo_tried"],"description":"Optional funnel step; omitted means view. unavailable: the page was shown sold out or not on sale. tier_select / cart: chose tickets. details: buyer details entered. checkout_start: the order exists. payment_open / payment_failed: the payment step. hold_expired: the checkout timer ran out. promo_tried: a code was entered. Paid is never a step: it comes from orders. The commerce pixel sends each step by the command of the same name. A one-shot step already stored for the journey answers 200 with duplicate: true."},"step_outcome":{"type":"string","enum":["sold_out","not_on_sale","sales_ended","declined","verification","other","worked","did_not_work"],"description":"Coarse outcome (ENG-2311). unavailable: sold_out | not_on_sale | sales_ended. payment_failed: declined | verification | other. promo_tried: worked | did_not_work. An outcome the step cannot carry is ignored. Never send a promo code or anything the buyer typed."},"time_zone":{"type":"string","maxLength":64,"description":"The browser's time zone name (for example America/Chicago). AXYN reads a country from it, and a state or province where one zone is one state, then discards it. Approximate. An unknown zone is ignored."},"device_class":{"type":"string","enum":["mobile","desktop"],"description":"Phone or computer (ENG-2311). Anything else is ignored."},"referrer_host":{"type":"string","maxLength":255,"description":"Host name of the site that sent the visitor (ENG-2311). Host only: a path or full address is ignored."},"landing_path":{"type":"string","maxLength":1024,"description":"Path and query string of the page the visit started on (ENG-2314), where a link carries its campaign. Scrubbed before storage: no fragment, no value on a parameter that names identity or a secret, no value that looks like an email or a written phone number."},"utm_source":{"type":"string","maxLength":128,"description":"Campaign source (ENG-2314). Read from landing_path when not sent. Stored lower-case."},"utm_medium":{"type":"string","maxLength":128},"utm_campaign":{"type":"string","maxLength":128},"visitor_key":{"type":"string","minLength":8,"maxLength":128,"description":"Opaque first-party id that lets a journey span visits for up to 30 days (ENG-2319). One per organizer. Never email-derived."},"order_id":{"type":"string","format":"uuid","description":"Partner commerce pixel only (ENG-2470): on checkout_start or payment_open, the id of the order the partner's server just created. AXYN links that order to this journey when the order is this organizer's, for this event or series, created in the last hour and not already linked. Used for the link only and never stored on the funnel record. Ignored on other steps and surfaces; a missing or unknown id never refuses the step."},"items":{"type":"array","maxItems":20,"description":"The ticket or pass types in hand at this step (ENG-2310). Priced by AXYN from the catalog; a price sent here is ignored. An item that is not a ticket type of this event or series, or has a quantity outside 1 to 100, is dropped and the step still counts.","items":{"type":"object","required":["ticket_tier_id","quantity"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":100}}}},"event_id":{"type":"string","format":"uuid","description":"Optional: the program of this series the buyer was on. Kept on the fact when it belongs to the series; otherwise ignored."}}}}}},"responses":{"200":{"description":"Already stored: this one-shot step was recorded for the journey before (a reload, a retry, a second copy of the pixel). Nothing new was written.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","nullable":true},"duplicate":{"type":"boolean"}}}}}}}},"201":{"description":"View fact stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"202":{"description":"Accepted and dropped: funnel ingest was at its ceiling (ENG-2317). Nothing was stored; do not retry. A beacon never queues behind, or competes with, an order."},"204":{"description":"Funnel analytics is switched off for the platform (ENG-2317). Nothing was read or stored."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation failed, pixel_disabled when Partner page insights is off for the series, or embed_analytics_disabled when analytics on partner embeds is off for the series"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/commerce-pixel.js":{"get":{"tags":["public","partner"],"summary":"Partner headless-checkout view pixel script (ENG-623 / ENG-635)","operationId":"getCommercePixelScript","description":"Static JS a partner installs on their ticket page via <script src>. No browser API key required (ENG-635). Never send secrets in page HTML. Never sends fetch(...) to /v1/events/{eventId}/views until axyn('consent', { analytics: true }). One command per funnel step: axyn('view' | 'tier_select' | 'cart' | 'checkout_start', { eventId }), or { seriesId } for a series and its passes (posted to /v1/productions/{productionId}/views), each sent once per session and event or series. Paid comes from orders, never the pixel. No email, name, phone, or full URL is ever read. See product/axyn/developer/partner-commerce-insights-privacy.md.","security":[],"responses":{"200":{"description":"Pixel script body","content":{"application/javascript":{"schema":{"type":"string"}}}}}}},"/v1/events/{eventId}/cancellation-status":{"get":{"tags":["public"],"summary":"Public cancellation status for an event","operationId":"getEventCancellationStatus","description":"Credential-free status probe (rate-limited by IP) — surfaces \"cancelled\" without exposing the buyer's full order.","security":[],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"type":"string"},"cancelled_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/events/{eventId}/mass-refund-failures":{"get":{"tags":["event-lifecycle"],"summary":"List terminal mass-refund dead-letter failures for an event","operationId":"listEventMassRefundFailures","description":"M46n — organizer read of `mass_refund_failures` for the event's latest cancellation. Dual-auth: API key `catalog:read` or staff JWT `event.read` + `x-tenant-id`. List filters to linked refund requests still `failed`; use POST …/retry (ENG-510) to requeue.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"cancellation_event_id":{"type":"string","format":"uuid"},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"cancellation_event_id":{"type":"string","format":"uuid"},"ticket_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid","nullable":true},"refund_request_id":{"type":"string","format":"uuid","nullable":true},"failure_reason":{"type":"string"},"failure_detail":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"total_count":{"type":"integer"},"next_offset":{"type":"integer","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/{eventId}/mass-refund-failures/{failureId}/retry":{"post":{"tags":["event-lifecycle"],"summary":"Requeue a terminal mass-refund failure for another Stripe attempt","operationId":"retryEventMassRefundFailure","description":"ENG-510 — flips the linked `ticket_refund_requests` row back to `approved` and reopens the cancellation refund drain when needed. Dual-auth: API key `catalog:write` or staff JWT `event.cancel` + `x-tenant-id`. Keeps the `mass_refund_failures` audit row.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"failureId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Requeued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"failure_id":{"type":"string","format":"uuid"},"refund_request_id":{"type":"string","format":"uuid"},"cancellation_event_id":{"type":"string","format":"uuid"},"refund_drain_reopened":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Conflict — refund request missing/not failed, or cancellation mismatch","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["refund_request_not_found","refund_request_not_failed","cancellation_mismatch"]}}}}}},"502":{"description":"Requeue failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","enum":["requeue_failed"]}}}}}}}}},"/v1/me/event-photos/{eventId}":{"get":{"tags":["photos","buyer"],"summary":"List event photos the caller is entitled to view","operationId":"listBuyerEventPhotos","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/event-photos/{eventId}/consent":{"post":{"tags":["photos","buyer"],"summary":"Record buyer's consent decision for event photos","operationId":"setBuyerEventPhotoConsent","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consent"],"properties":{"consent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"consent":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/photo-removal-requests":{"post":{"tags":["photos","buyer"],"summary":"Request removal of a specific event photo","operationId":"createPhotoRemovalRequest","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id","photo_id","reason"],"properties":{"event_id":{"type":"string","format":"uuid"},"photo_id":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":1}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/marketing-consents":{"post":{"tags":["consents","buyer"],"summary":"Record buyer marketing consent for one tenant","operationId":"setBuyerMarketingConsent","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenant_id","consent"],"properties":{"tenant_id":{"type":"string","format":"uuid"},"consent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"consent":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"get":{"tags":["consents","buyer"],"summary":"List the caller's marketing consents","operationId":"listBuyerMarketingConsents","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/cross-organizer-consent":{"get":{"tags":["consents","buyer"],"summary":"Get cross-organizer recommendation consent","operationId":"getBuyerCrossOrganizerConsent","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"marketing_consent_cross_organizer":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["consents","buyer"],"summary":"Set cross-organizer recommendation consent","operationId":"setBuyerCrossOrganizerConsent","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant"],"properties":{"grant":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"result_code":{"type":"string"},"marketing_consent_cross_organizer":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/cross-organizer-recommendations":{"get":{"tags":["consents","buyer"],"summary":"Get cross-organizer event recommendations","operationId":"listBuyerCrossOrganizerRecommendations","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/me/nps-responses/{ticketId}":{"post":{"tags":["buyer"],"summary":"Submit an NPS response for a ticket","operationId":"submitBuyerNpsResponse","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["score"],"properties":{"score":{"type":"integer","minimum":0,"maximum":10},"comment":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ticket_id":{"type":"string","format":"uuid"},"score":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/me/next-event-recommendations":{"get":{"tags":["buyer"],"summary":"Get recommended next events for the caller","operationId":"listBuyerNextEventRecommendations","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/profile":{"patch":{"tags":["buyer"],"summary":"Update the caller's profile","operationId":"updateBuyerProfile","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"display_name":{"type":"string","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/guest-orders/claim":{"post":{"tags":["buyer"],"summary":"Bind guest-checkout orders to the caller's account","operationId":"claimGuestOrders","description":"M24-guest-claim — binds every cross-tenant ticket_orders row where purchaser_user_id IS NULL AND purchaser_email matches the JWT email.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"bound_orders":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/tickets/{ticketId}/upgrade-requests":{"post":{"tags":["upgrades","buyer"],"summary":"Create a tier-upgrade intent for a ticket","operationId":"createTicketUpgradeRequest","description":"M24c — snapshots source total_paid + target tier price under row locks; substrate only, no Stripe charge.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_tier_id"],"properties":{"target_tier_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"upgrade_request_id":{"type":"string","format":"uuid"},"delta_cents":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/me/tickets/{ticketId}/upgrade-requests/cancel":{"post":{"tags":["upgrades","buyer"],"summary":"Cancel an open tier-upgrade request","operationId":"cancelTicketUpgradeRequest","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["upgrade_request_id"],"properties":{"upgrade_request_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"upgrade_request_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/me/tickets/{ticketId}/upgrade-requests/{requestId}/pay":{"post":{"tags":["upgrades","buyer"],"summary":"Pay the all-in upgrade delta","operationId":"payTicketUpgradeRequest","description":"ENG-793 — creates a PaymentIntent for due_now = all_in(target) minus remaining_net. Webhook fulfill moves the same pass in place (ENG-811). Do not charge the face-only intent snapshot.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PaymentIntent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/UpgradePaymentStart"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/me/tickets/{ticketId}/upgrade-options":{"get":{"tags":["upgrades","buyer"],"summary":"List all-in upgrade options for a ticket","operationId":"listTicketUpgradeOptions","description":"ENG-794 — eligible target types with perks and due_now_cents (all-in target minus remaining_net). Hide Upgrade when available is false.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Options listed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"available":{"type":"boolean"},"reason_code":{"type":"string","nullable":true},"source":{"type":"object","nullable":true},"options":{"type":"array","items":{"type":"object","properties":{"target_tier_id":{"type":"string","format":"uuid"},"target_tier_name":{"type":"string"},"due_now_cents":{"type":"integer","nullable":true},"target_all_in_cents":{"type":"integer","nullable":true},"eligible":{"type":"boolean"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/tickets/{ticketId}/live-qr/mint":{"post":{"tags":["buyer","tickets"],"summary":"Mint a live QR slot for an owned ticket","operationId":"mintLiveQrForOwnedTicket","description":"Mint a rotating live pass slot for a ticket the caller owns (buyer JWT). On an additional device the API may return 403 with error step_up_required and data.sid.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash"],"properties":{"device_key_hash":{"type":"string","description":"SHA-256 hex of the durable device key.","pattern":"^[0-9a-f]{64}$"}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Device step-up required. Body: { success: false, error: \"step_up_required\", data: { sid } }."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me/tickets/{ticketId}/live-qr/extend":{"post":{"tags":["buyer","tickets"],"summary":"Extend / rotate a live QR slot for an owned ticket","operationId":"extendLiveQrForOwnedTicket","description":"Rotate the current live pass slot for an existing device session.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sid":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me/tickets/{ticketId}/live-qr/confirm-step-up":{"post":{"tags":["buyer","tickets"],"summary":"Confirm live QR device step-up for an owned ticket","operationId":"confirmLiveQrStepUpForOwnedTicket","description":"Confirm a pending live pass device step-up after the holder opens the emailed confirm URL (`sid` + signed `confirm`). The 403 sid alone is not enough. Returns a minted slot on success.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid","confirm"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sid":{"type":"string","format":"uuid"},"confirm":{"type":"string","minLength":36,"description":"Ed25519-signed `su1` secret from the holder-email confirm URL query `confirm`. The 403 `sid` is not sufficient."}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me/orders/{orderId}/refund-eligibility":{"get":{"tags":["refunds","buyer"],"summary":"Preview refund eligibility for an order","operationId":"getBuyerRefundEligibility","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"eligible":{"type":"boolean"},"refundable_cents":{"type":"integer"},"policy":{"$ref":"#/components/schemas/RefundPolicy"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/refund-requests":{"post":{"tags":["refunds","buyer"],"summary":"Submit a refund request for one ticket or the whole order","operationId":"createBuyerRefundRequest","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id","reason"],"properties":{"order_id":{"type":"string","format":"uuid"},"ticket_id":{"type":"string","format":"uuid","description":"One ticket on the order to refund. Omit to request the whole order."},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Trimmed server-side; 1..2000 characters after trimming."}}}}}},"responses":{"200":{"description":"A pending request for the same order and ticket already exists (idempotent replay); it is returned unchanged.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["refund_request","escalation_path"],"properties":{"refund_request":{"type":"object","required":["id","tenant_id","order_id","ticket_id","requester_user_id","status","requested_amount_cents","approved_amount_cents","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"ticket_id":{"type":["string","null"],"format":"uuid","description":"Null for a whole-order request."},"requester_user_id":{"type":"string","format":"uuid"},"reviewer_user_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string"},"requested_amount_cents":{"type":"integer"},"approved_amount_cents":{"type":"integer"},"stripe_refund_id":{"type":["string","null"]},"reviewed_at":{"type":["string","null"],"format":"date-time"},"processed_at":{"type":["string","null"],"format":"date-time"},"tickets_restored_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"escalation_path":{"type":"object","required":["email","sla_hours"],"properties":{"email":{"type":"string"},"sla_hours":{"type":"integer"}}}}},"code":{"type":"string","const":"refund_request_already_pending"}}}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["refund_request","escalation_path"],"properties":{"refund_request":{"type":"object","required":["id","tenant_id","order_id","ticket_id","requester_user_id","status","requested_amount_cents","approved_amount_cents","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"ticket_id":{"type":["string","null"],"format":"uuid","description":"Null for a whole-order request."},"requester_user_id":{"type":"string","format":"uuid"},"reviewer_user_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string"},"requested_amount_cents":{"type":"integer"},"approved_amount_cents":{"type":"integer"},"stripe_refund_id":{"type":["string","null"]},"reviewed_at":{"type":["string","null"],"format":"date-time"},"processed_at":{"type":["string","null"],"format":"date-time"},"tickets_restored_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"escalation_path":{"type":"object","required":["email","sla_hours"],"properties":{"email":{"type":"string"},"sla_hours":{"type":"integer"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"Not refundable (ineligibility code in `error`, e.g. refund_window_closed, refunds_disabled, order_not_refundable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error."}}},"get":{"tags":["refunds","buyer"],"summary":"List the caller's refund requests","operationId":"listBuyerRefundRequests","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/me/ticket-transfer-offers":{"get":{"tags":["transfers","buyer"],"summary":"List incoming transfer offers addressed to the caller","operationId":"listIncomingTicketTransferOffers","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/notification-preferences":{"get":{"tags":["notifications","buyer"],"summary":"Get the caller's notification preferences","operationId":"getBuyerNotificationPreferences","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"opt_outs":{"type":"array","items":{"type":"string"}},"quiet_hours":{"type":"object","nullable":true,"properties":{"start_local":{"type":"string"},"end_local":{"type":"string"},"timezone":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["notifications","buyer"],"summary":"Upsert notification opt-outs and/or quiet-hours (partial)","operationId":"upsertBuyerNotificationPreferences","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opt_outs":{"type":"array","items":{"type":"string"},"nullable":true},"quiet_hours":{"type":"object","nullable":true,"properties":{"start_local":{"type":"string"},"end_local":{"type":"string"},"timezone":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"tags":["notifications","buyer"],"summary":"Replace notification opt-outs and/or quiet-hours (full)","operationId":"replaceBuyerNotificationPreferences","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["opt_outs"],"properties":{"opt_outs":{"type":"array","items":{"type":"string"}},"quiet_hours":{"type":"object","nullable":true,"properties":{"start_local":{"type":"string"},"end_local":{"type":"string"},"timezone":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"replaced":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/fraud-claims":{"post":{"tags":["fraud-claims","buyer"],"summary":"Submit a fraud claim for a ticket","operationId":"createFraudClaim","description":"M28h — authenticated fraud-claim submission. Tenant is derived from the ticket row server-side; an unknown ticket collapses to opaque ticket_not_found.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticket_id","description"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"description":{"type":"string","minLength":1},"evidence_urls":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/vouchers/redeem":{"post":{"tags":["vouchers","buyer"],"summary":"Redeem a voucher against an order","operationId":"redeemVoucher","description":"M28b — flips a voucher to terminal redeemed + binds it to the target order. applied_cents is what future checkout composition subtracts from what Stripe is charged.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["voucher_code","order_id"],"properties":{"voucher_code":{"type":"string"},"order_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"voucher_id":{"type":"string","format":"uuid"},"applied_cents":{"type":"integer"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/vouchers/{voucherId}/void":{"post":{"tags":["vouchers"],"summary":"Void an active voucher (organizer)","operationId":"voidVoucher","description":"M28b-void — organizer-staff terminal void of an active voucher. SINGLE writer of vouchers.status active → voided.","security":[{"bearerAuth":[]}],"parameters":[{"name":"voucherId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"voucher_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/ticket-url/{token}":{"get":{"tags":["public","tickets"],"summary":"Public bearer-token ticket URL lookup","operationId":"getTicketByBearerToken","description":"M17a — credential-free lookup: the 32-byte token IS the credential. Rate-limited per IP + token-prefix.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque 32-byte ticket URL token.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ticket":{"type":"object"},"tenant":{"oneOf":[{"$ref":"#/components/schemas/BuyerTenantBrand"},{"type":"null"}]},"event":{"type":["object","null"],"description":"The ticket's event: title, times, venue and the organizer message. ENG-2337 / ENG-2338: for a pass, and for a ticket whose series hides its lineup from ticket holders (`series.lineup_on_live_pass` false), `title` is the series title. Times and venue stay those of the ticket's own program; a pass's dates are in `pass`.","properties":{"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. Minimum age for this event: 0 (all ages), 18 or 21. When 18 or 21, show the age and that the guest needs photo ID. For a pass, use each row of pass_admits instead."}}},"series":{"type":["object","null"],"description":"ENG-2337. The series the ticket's program belongs to. Null for a standalone event.","required":["title","lineup_on_live_pass"],"properties":{"title":{"type":"string"},"lineup_on_live_pass":{"type":"boolean","description":"Whether ticket holders see the series' programs. False: no program is named, and `pass_admits` holds only the holder's own rows."}}},"pass":{"type":["object","null"],"description":"ENG-2338. Only when the ticket's type is a pass: the dates it is valid, the one place its programs share and the age that gets its holder into all of them. Every value comes from the programs it admits that are not cancelled, never from `event`.","required":["valid_from","valid_to","place","minimum_age"],"properties":{"valid_from":{"type":["string","null"],"format":"date-time","description":"Start of the first program the pass admits that is not cancelled."},"valid_to":{"type":["string","null"],"format":"date-time","description":"Start of the last program the pass admits that is not cancelled."},"place":{"type":["string","null"],"description":"The one place every program the pass admits shares. Null when they are in different places, or when it admits none."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"The highest minimum age among the programs the pass admits: 0 (all ages), 18 or 21. 0 when it admits none."}}},"pass_admits":{"type":"array","description":"Snapshotted pass admit strip from event_ticket_pass_admits (empty for single-occurrence tickets). ENG-2337: when `series.lineup_on_live_pass` is false, only rows whose `held` is not null.","items":{"$ref":"#/components/schemas/TicketUrlPassAdmitStrip"}}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/apple-pass":{"get":{"tags":["public","tickets","wallet"],"summary":"Download Apple Wallet .pkpass for a ticket URL credential","operationId":"getAppleWalletPass","description":"ENG-213 — signed Apple Wallet event ticket (Pass shelf). Accepts pass share code or long bearer. No admit barcode; Live Pass URL is on the pass. Rate-limited. Opaque 404 on miss.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque ticket-url share code or bearer token.","schema":{"type":"string"}}],"responses":{"200":{"description":"Signed Apple Wallet pass","content":{"application/vnd.apple.pkpass":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Apple Pass credentials unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/v1/ticket-url/{token}/transfer-offers":{"post":{"tags":["transfers","public"],"summary":"Issue a transfer offer from a ticket-url bearer","operationId":"createTicketUrlTransferOffer","description":"Guest Send a pass. Ticket-url bearer is view+door only. Issue requires device_key_hash of a confirmed Live Pass session, or returns 403 step_up_required with sid.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque ticket-url bearer token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient_email","device_key_hash"],"properties":{"recipient_email":{"type":"string","format":"email"},"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"ttl_seconds":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"step_up_required (data.sid) or device_session_cap"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/transfer-offers/revoke":{"post":{"tags":["transfers","public"],"summary":"Revoke a pending transfer offer from a ticket-url bearer","operationId":"revokeTicketUrlTransferOffer","description":"Revoke a pending transfer offer using ticket-url holdership.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/transfer-offers/resend":{"post":{"tags":["transfers","public"],"summary":"Resend a pending transfer offer email","operationId":"resendTicketUrlTransferOffer","description":"Resend transfer email for a pending offer identified by share_code. Same device_key_hash / step_up_required gate as issue. Revoke is not gated.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["share_code","device_key_hash"],"properties":{"share_code":{"type":"string"},"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"step_up_required (data.sid) or device_session_cap"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/upgrade-options":{"get":{"tags":["upgrades","public"],"summary":"List all-in upgrade options from a ticket-url bearer","operationId":"listTicketUrlUpgradeOptions","description":"Guest upgrade quote. Ticket-url bearer proves holdership; no buyer JWT.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Options listed"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/upgrade-requests":{"post":{"tags":["upgrades","public"],"summary":"Issue a tier-upgrade intent from a ticket-url bearer","operationId":"createTicketUrlUpgradeRequest","description":"Guest upgrade issue. Ticket-url bearer proves holdership; no buyer JWT.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_tier_id"],"properties":{"target_tier_id":{"type":"string","format":"uuid"},"ttl_seconds":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Created"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/upgrade-requests/cancel":{"post":{"tags":["upgrades","public"],"summary":"Cancel an open upgrade request from a ticket-url bearer","operationId":"cancelTicketUrlUpgradeRequest","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/upgrade-requests/{requestId}/pay":{"post":{"tags":["upgrades","public"],"summary":"Pay the all-in upgrade delta from a ticket-url bearer","operationId":"payTicketUrlUpgradeRequest","description":"Guest upgrade pay. Returns Stripe client_secret and due_now_cents.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PaymentIntent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/UpgradePaymentStart"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/upgrade-invites/{token}":{"get":{"tags":["upgrades"],"summary":"Read a staff upgrade invite","operationId":"getUpgradeInvite","description":"ENG-801 guest-first. 410 when expired. already_upgraded true means do not charge again.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invite, event, organizer brand, and upgrade options.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"tenant":{"oneOf":[{"$ref":"#/components/schemas/BuyerTenantBrand"},{"type":"null"}]}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"Invite expired. Original Live Pass still works."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/upgrade-invites/{token}/upgrade-requests":{"post":{"tags":["upgrades"],"summary":"Issue an upgrade from a staff invite","operationId":"issueUpgradeForInvite","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_tier_id"],"properties":{"target_tier_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Already pending."},"201":{"description":"Issued."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"description":"Invite expired."}}}},"/v1/upgrade-invites/{token}/upgrade-requests/cancel":{"post":{"tags":["upgrades"],"summary":"Cancel an invite upgrade request","operationId":"cancelUpgradeForInvite","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/upgrade-invites/{token}/upgrade-requests/{requestId}/pay":{"post":{"tags":["upgrades"],"summary":"Start Stripe pay for an invite upgrade","operationId":"payUpgradeForInvite","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PaymentIntent created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/UpgradePaymentStart"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/ticket-url/{token}/live-qr/mint":{"post":{"tags":["public","tickets"],"summary":"Mint a live QR slot for a bearer ticket URL","operationId":"mintLiveQrForBearerToken","description":"Mint a rotating live pass slot for a guest ticket-url bearer. Rate-limited. On an additional device the API may return 403 with error step_up_required and data.sid; the purchaser then confirms via email.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque bearer ticket-url token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash"],"properties":{"device_key_hash":{"type":"string","description":"SHA-256 hex of the durable device key.","pattern":"^[0-9a-f]{64}$"}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Device step-up required. Body: { success: false, error: \"step_up_required\", data: { sid } }."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/live-qr/extend":{"post":{"tags":["public","tickets"],"summary":"Extend / rotate a live QR slot for a bearer ticket URL","operationId":"extendLiveQrForBearerToken","description":"Rotate the current live pass slot for an existing device session.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque bearer ticket-url token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sid":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/live-qr/confirm-step-up":{"post":{"tags":["public","tickets"],"summary":"Confirm live QR device step-up for a bearer ticket URL","operationId":"confirmLiveQrStepUpForBearerToken","description":"Confirm a pending live pass device step-up after the holder opens the emailed confirm URL (`sid` + signed `confirm`). The 403 sid alone is not enough. Returns a minted slot on success.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque bearer ticket-url token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid","confirm"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sid":{"type":"string","format":"uuid"},"confirm":{"type":"string","minLength":36,"description":"Ed25519-signed `su1` secret from the holder-email confirm URL query `confirm`. The 403 `sid` is not sufficient."}}}}}},"responses":{"200":{"description":"Live QR slot minted or extended.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["token","kid","sid","slot_exp","window_expires_at","bind_action","server_now","pack"],"properties":{"token":{"type":"string","description":"Signed live QR v3 payload for the current slot."},"kid":{"type":"string","description":"Signing key id."},"sid":{"type":"string","format":"uuid","description":"Device session id bound to this mint."},"slot_exp":{"type":"integer","description":"Unix ms when the current rotating slot expires."},"window_expires_at":{"type":"string","format":"date-time","description":"End of the live-QR admit window for this session."},"bind_action":{"type":"string","enum":["reuse","bind_silent"]},"server_now":{"type":"string","format":"date-time","description":"Server clock at mint. Client uses this offset to pick the current pack slot."},"pack":{"type":"object","description":"Pre-signed slot pack for upcoming 45s slots through window_expires_at (ENG-828). `sigs[i]` is the Ed25519 signature (base64url) of slot `start_slot + i`; the client assembles `v3.<payload>.<sig>` and holds no signing key.","required":["kid","ref","tenant","event","sid","start_slot","slot_ms","sigs"],"properties":{"kid":{"type":"string"},"ref":{"type":"string"},"tenant":{"type":"string"},"event":{"type":"string"},"sid":{"type":"string","format":"uuid"},"start_slot":{"type":"integer"},"slot_ms":{"type":"integer"},"sigs":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/event-previews/{token}":{"get":{"tags":["public"],"summary":"Public bearer-token draft event preview","operationId":"getEventPreviewByBearerToken","description":"M13-draft-preview (OD2.5) — credential-free draft event preview. Returns the same shape as GET /v1/events/{eventId} wrapped with preview: true so the buyer UI can watermark + suppress checkout.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque 32-byte draft-preview token.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"preview":{"type":"boolean"},"event":{"type":"object"}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/estate-claims":{"post":{"tags":["estate-claims","public"],"summary":"Submit a public estate claim on a deceased buyer's order","operationId":"submitEstateClaim","description":"M28f — D12.1 buyer death / estate handling. NO auth — the claimant is, by definition, NOT an AXYN account holder. Tenant is derived server-side from the order row.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id","claimant_name","claimant_email","claimant_relationship"],"properties":{"order_id":{"type":"string","format":"uuid"},"claimant_name":{"type":"string","minLength":1},"claimant_email":{"type":"string","format":"email"},"claimant_relationship":{"type":"string"},"death_certificate_url":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/auth/account-recovery/request":{"post":{"tags":["account-recovery","public"],"summary":"Submit a public account-recovery request","operationId":"submitAccountRecoveryRequest","description":"M28g — D12.3 identity stolen / account compromised. NO auth — by definition the user whose credentials are compromised cannot present a valid JWT.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recovery_email"],"properties":{"recovery_email":{"type":"string","format":"email"},"recovery_phone":{"type":"string","nullable":true},"last_payment_card_last_4":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/on-sale-notify-requests":{"post":{"tags":["on-sale-notify","public"],"summary":"Ask to be emailed when a paused event is back on sale","operationId":"submitOnSaleNotifyRequest","description":"ENG-2257 — public, guest-first. Accepted only while buyers read the event as paused for organizer payout setup (`status: paused`, `sales_paused_reason: payout_not_ready`); every other state answers 409 `on_sale_notify_not_available`. Refused once the event's sales window has closed. The guest is emailed once when the event can be bought again (a ticket type inside its own sales window). New and repeat sign-ups answer the same 202. Rate-limited per IP + hashed email and per IP.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id","email"],"properties":{"event_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email","maxLength":320}}}}}},"responses":{"202":{"description":"on_sale_notify_requested (a repeat sign-up answers the same, so the response never says whether an address is already listed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnSaleNotifyRequestResponse"}}}},"400":{"description":"invalid_event_id | invalid_email"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"on_sale_notify_not_available"},"429":{"description":"rate limit exceeded"},"502":{"description":"on_sale_notify_failed (retryable)"}}}},"/v1/waitlist-joins":{"post":{"tags":["waitlist","public"],"summary":"Join the sold-out GA waitlist","operationId":"submitWaitlistJoin","description":"ENG-1597 — public waitlist join. No payment or inventory hold. Whether the waitlist is open is the organizer's `event.waitlist_join_mode` (ENG-1598): `off` always refuses, `always` accepts while the sales window is open, and `sold_out` accepts only once no sellable units remain. An operational `paused` on the waitlist config refuses on top of that. Duplicate open ask returns already_joined (200).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_event_id","ticket_tier_id","email","quantity"],"properties":{"venue_event_id":{"type":"string","format":"uuid"},"ticket_tier_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"quantity":{"type":"integer","minimum":1,"maximum":100},"allow_alternates":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"already_joined"},"201":{"description":"waitlist_joined"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"waitlist_not_available"}}}},"/v1/waitlist-status":{"post":{"tags":["waitlist","public"],"summary":"Proof-gated waitlist status lookup","operationId":"getWaitlistStatus","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference_id","email"],"properties":{"reference_id":{"type":"string"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"status"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/waitlist-claims/{token}":{"get":{"tags":["waitlist","public"],"summary":"Resolve a waitlist claim token (no PaymentIntent)","operationId":"getWaitlistClaim","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"offer facts"},"404":{"description":"unknown, rotated, or spent (order already paid or refunded)"},"410":{"description":"expired: the claim window closed, or the soft-hold order expired, was cancelled, or failed"}}}},"/v1/waitlist-claims/{token}/payments/start":{"post":{"tags":["waitlist","public","checkout"],"summary":"Bind purchaser and start Stripe checkout for a waitlist hold","operationId":"startWaitlistClaimPayment","security":[{"bearerAuth":[]}],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"PaymentIntent started"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"unknown, rotated, or spent (order already paid or refunded)"},"410":{"description":"expired: the claim window closed, or the soft-hold order expired, was cancelled, or failed"}}}},"/v1/tenants/{tenantId}/events/{eventId}/waitlist-config":{"get":{"tags":["waitlist","staff"],"summary":"Read waitlist config for an event","description":"Read-only `join_mode` in the response echoes `event.waitlist_join_mode` (ENG-1598) so a client can tell whether guests may join without a second source of truth. It is changed on the event, not here; PATCH ignores it.","operationId":"getWaitlistConfig","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"config"}}},"patch":{"tags":["waitlist","staff"],"summary":"Update waitlist config for an event","description":"Read-only `join_mode` in the response echoes `event.waitlist_join_mode` (ENG-1598) so a client can tell whether guests may join without a second source of truth. It is changed on the event, not here; PATCH ignores it.","operationId":"patchWaitlistConfig","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paused":{"type":"boolean"},"mode":{"type":"string","enum":["manual","auto_exact","smart"]},"claim_ttl_seconds":{"type":"integer","minimum":900,"maximum":3600},"tier_bind_ids":{"type":"array","minItems":1,"description":"Ticket types guests may join for. At least one; an empty list is refused with 400 `waitlist_tier_bind_required` (ENG-1598). Omit to leave the binds alone. No stored binds (never set) means every public type.","items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"updated config"}}}},"/v1/tenants/{tenantId}/events/{eventId}/waitlist-entries":{"get":{"tags":["waitlist","staff"],"summary":"List waitlist entries for an event","operationId":"listWaitlistEntries","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"entries"}}}},"/v1/tenants/{tenantId}/waitlist-entries/{entryId}/offers":{"post":{"tags":["waitlist","staff"],"summary":"Create an idempotent waitlist offer with inventory soft-hold","operationId":"createWaitlistOffer","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"entryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","offered_tier_id","quantity"],"properties":{"kind":{"type":"string","enum":["exact_purchase","alternate_purchase","upgrade_invite"]},"offered_tier_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"offer created"}}}},"/v1/tenants/{tenantId}/waitlist-entries/{entryId}/remove":{"post":{"tags":["waitlist","staff"],"summary":"Remove a waitlist entry and release any hold","operationId":"removeWaitlistEntry","security":[{"bearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"entryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"removed"}}}},"/v1/group-sales-requests":{"post":{"tags":["group-sales","public"],"summary":"Submit an above-cap group-sales request","operationId":"submitGroupSalesRequest","description":"M23-group-sales — public above-cap group-sales request intake (D3.3). Unauthenticated; no tenant API key. Tenant + venue_event derived server-side from `ticket_tier_id` (tier id is the credential). Idempotent on open `(ticket_tier_id, requester_email)` → `group_sales_request_already_submitted` (200).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticket_tier_id","requester_name","requester_email","quantity_desired"],"properties":{"ticket_tier_id":{"type":"string","format":"uuid","description":"Ticket tier the buyer tried to exceed. Tenant/event are derived server-side; do not send tenant_id."},"requester_name":{"type":"string","minLength":1,"maxLength":200},"requester_email":{"type":"string","format":"email","minLength":3,"maxLength":320},"requester_phone":{"type":"string","nullable":true,"minLength":1,"maxLength":32},"quantity_desired":{"type":"integer","minimum":1,"maximum":10000,"description":"Must be strictly above the tier max_per_order (default 8) or the API returns quantity_within_cap."},"notes":{"type":"string","nullable":true,"minLength":1,"maxLength":4000}}}}}},"responses":{"200":{"description":"Idempotent — open request already exists for this tier + email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupSalesRequestSubmitEnvelope"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupSalesRequestSubmitEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Business refusal (quantity_within_cap | tier_not_accepting_group_sales)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupSalesRequestSubmitEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/auth/federation/token-exchange":{"post":{"tags":["federation"],"summary":"Exchange a partner user token for an AXYN session","operationId":"exchangePartnerToken","description":"Partner token exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)). A registered federation partner trades its own signed user token (a JWT) for an AXYN buyer session.\n\n- AXYN picks the partner from the token's `iss`, then verifies signature, issuer and audience against that partner's registered JWKS and audience.\n- A partner must be registered **and** named in this deployment's partner allowlist; a registered partner that is not allowlisted is refused like an unknown issuer.\n- The token must carry `sub` and `email` and must not be anonymous (`is_anonymous: true`).\n- The partner identity (`partner_id`, `sub`) is linked to one AXYN account: an existing account with the same email (`email_match`) or a new buyer account (`explicit_link`). Organizer and platform-admin accounts are never reachable this way (403).\n\nEvery partner uses this one contract; there is no partner-specific path. Accepts `application/json` or `application/x-www-form-urlencoded`.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeRequest"}}}},"responses":{"200":{"description":"AXYN buyer session for the partner's user (RFC 8693 §2.2 fields inside the AXYN envelope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeSession"}}}},"400":{"description":"Malformed exchange request (`invalid_request`, `unsupported_grant_type`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"401":{"description":"The subject token is not from a registered partner this deployment allowlists, fails verification, is anonymous, or has no email (`invalid_federation_token`); or the account could not be provisioned or linked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"403":{"description":"The email belongs to an AXYN organizer or platform admin account (`privileged_account_requires_direct_sign_in`). Those accounts sign in to AXYN directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"A partner, link or grant lookup, or the session mint, failed. Retry later; never treated as a refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}}}}},"/v1/auth/federation/seeat-to-axyn":{"post":{"tags":["federation"],"summary":"Deprecated alias of the partner token exchange","operationId":"exchangePartnerTokenBearerAlias","deprecated":true,"description":"Deprecated. Same handler, partner registry, allowlist and response as `POST /v1/auth/federation/token-exchange`; the subject token is read from `Authorization: Bearer` instead of the body. Responses carry `Deprecation: true` and a `Link` to the successor. Removed once no deployed partner client calls it.","security":[],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","pattern":"^Bearer .+"},"description":"`Bearer <partner user JWT>`."}],"responses":{"200":{"description":"AXYN buyer session for the partner's user (RFC 8693 §2.2 fields inside the AXYN envelope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeSession"}}}},"400":{"description":"Malformed exchange request (`invalid_request`, `unsupported_grant_type`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"401":{"description":"The subject token is not from a registered partner this deployment allowlists, fails verification, is anonymous, or has no email (`invalid_federation_token`); or the account could not be provisioned or linked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"403":{"description":"The email belongs to an AXYN organizer or platform admin account (`privileged_account_requires_direct_sign_in`). Those accounts sign in to AXYN directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"A partner, link or grant lookup, or the session mint, failed. Retry later; never treated as a refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTokenExchangeError"}}}}}}},"/v1/ticket-url/{token}/live-qr/resend-step-up":{"post":{"tags":["public","tickets"],"summary":"Resend live pass step-up email for a bearer ticket URL","operationId":"resendLiveQrStepUpForBearerToken","description":"Resend the device confirmation email for a pending step-up session. Ticket-url bearer is the credential. Body requires device_key_hash and sid from the step_up_required response.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque bearer ticket-url token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 hex of the durable device key."},"sid":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Step-up email resent.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Email send failed"}}}},"/v1/me/tickets/{ticketId}/live-qr/resend-step-up":{"post":{"tags":["buyer","tickets"],"summary":"Resend live pass step-up email for an owned ticket","operationId":"resendLiveQrStepUpForOwnedTicket","description":"Resend the device confirmation email for a pending step-up session on a ticket the caller owns. Requires buyer JWT.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_key_hash","sid"],"properties":{"device_key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 hex of the durable device key."},"sid":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Step-up email resent.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Email send failed"}}}},"/v1/tenants/{tenantId}/connect/payout-schedule":{"get":{"tags":["connect"],"summary":"Get Stripe Connect payout schedule for a tenant","operationId":"getTenantConnectPayoutSchedule","description":"ENG-598: staff JWT + settlement.read. Returns mirrored/live schedule (daily|weekly|monthly|manual). Instant payouts out of scope.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payout schedule view.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PayoutScheduleView"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Internal error."}}},"patch":{"tags":["connect"],"summary":"Update Stripe Connect payout schedule for a tenant","operationId":"patchTenantConnectPayoutSchedule","description":"ENG-598: staff JWT + settlement.payout_schedule.manage (organizer_admin). Updates via Stripe accounts.update; mirrors typed columns only after Stripe confirms. Instant payouts out of scope.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutScheduleUpdateRequest"}}}},"responses":{"200":{"description":"Updated payout schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PayoutScheduleView"}}}}}},"400":{"description":"Invalid schedule body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Connect account not linked, payouts are on a staff hold (code payout_hold_active, ENG-1626), the account is on manual payouts and not approved for early payouts (code early_payouts_not_approved, ENG-2034), or its schedule is not confirmed with Stripe (code payout_schedule_unconfirmed)."},"422":{"description":"Stripe rejects platform schedule edit; open Express."},"502":{"description":"Stripe update failed."},"503":{"description":"Stripe not configured."}}}},"/v1/tenants/{tenantId}/connect/early-payouts":{"get":{"tags":["connect"],"summary":"Early payouts for a tenant (read-only)","operationId":"getTenantConnectEarlyPayouts","description":"Staff JWT + settlement.read on the path tenant. Per series (or standalone event) with money on the current Connect account: the hold % a platform super admin set (payout % + hold % = 100%), what was paid early, what is held until after the event, what was paid above what the unit now keeps, and the estimated next payment. `production_id` or `event_id` (a standalone event) keeps that unit only (ENG-2408 A5). Viewer-only roles get every amount as 0 with `viewer_masked: true`; the `has_*` flags say which lines apply (A6). Nothing here changes a payout; the hold is set only by platform staff.","security":[{"bearerAuth":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"production_id","in":"query","required":false,"description":"Only this series. Never with event_id.","schema":{"type":"string","format":"uuid"}},{"name":"event_id","in":"query","required":false,"description":"Only this standalone event (a show in a series is paid with its series). Never with production_id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Early payouts view.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EarlyPayoutsView"}}}}}},"400":{"description":"tenantId, production_id or event_id is not a UUID, or both filters were given."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Internal error."}}}},"/v1/productions":{"get":{"tags":["catalog"],"summary":"List productions for the tenant (ENG-1634)","description":"Returns tenant productions for portfolio nesting (including empty series). ENG-1647 adds day_ticket_type_count and pass_count per production via two tenant-scoped batch queries (no N+1). M46c dual-auth: API key catalog:read or staff JWT event.read + x-tenant-id. Tenant never from body.","operationId":"listProductions","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"$ref":"#/components/parameters/PreviousEditionFor"}],"responses":{"200":{"description":"Productions listed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"productions":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["catalog"],"summary":"Create a production (ENG-138 minimal)","description":"Creates a production parent so occurrences can be linked for pass tiers. M46c dual-auth: API key catalog:write or staff JWT event.write + x-tenant-id. Tenant never from body.","operationId":"createProduction","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1},"description":{"type":["string","null"]},"house_rules":{"type":["string","null"],"maxLength":8000,"description":"ENG-1664 optional plain-text House rules for this series listing, not the venue."},"getting_in_parking":{"type":["string","null"],"maxLength":200,"description":"Where to park, in one line. Null or blank hides the line on the buyer page."},"getting_in_access":{"type":["string","null"],"maxLength":200,"description":"How to get in when getting in is not obvious (which door, step-free route, ID rules). Null or blank hides the line."},"getting_in_arrival":{"type":["string","null"],"maxLength":200,"description":"When to turn up, in one line. Null or blank hides the line."},"who_it_is_for":{"type":["string","null"],"maxLength":280,"description":"ENG-1663 series default Who it is for line. Hide when empty. Not a door check."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. The series minimum age: 0 (all ages), 18 or 21. Every program follows it unless it has its own. Raising it after tickets or passes are sold is allowed and ticket holders are not notified; tell them yourself."}},"additionalProperties":false}}}},"responses":{"201":{"description":"Production created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/productions/{productionId}":{"get":{"tags":["catalog"],"summary":"Get a production by id (ENG-1615 / ENG-1660)","description":"Public series catalog for Partner/SDK and hosted shop: title, story, cover, included shows, and buyable day-ticket + pass types. Staff JWT still returns the production parent for series home wayfinding. M46c dual-auth: API key catalog:read or staff JWT event.read + x-tenant-id. Tenant never from body. Draft integration (opt-in): with include_drafts=true, the owning organizer's own API key also gets its draft shows and their types, so it can build and test before publishing; each type keeps its own sale window and reports on_sale false until its show is published. Without the parameter the read is unchanged. Another organizer's key and the hosted shop never see a draft; for them the parameter is ignored. ENG-3017: each show's day-ticket types report seats left exactly as that show's own GET /v1/events/{eventId}/tiers does: a type linked to a shared area carries `area_remaining` (the area's seats left, counted once across the types sharing it) and its `inventory_total` / `inventory_available` report that area; `section_name` and `location_note` are stamped. ENG-3303: on a show with a capacity, every day-ticket type also carries `show_remaining` and `show_capacity`, the one limit those types share; count it once when adding seats left. Pass types are unchanged. If the seats left cannot be read the request fails (500) rather than send a type unprojected.","operationId":"getProduction","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"include_drafts","in":"query","required":false,"description":"Draft integration opt-in. `true` adds the series' draft shows (and their types) when the API key belongs to the organizer that owns the series and the call is not the hosted shop. Ignored otherwise; drafts never sell.","schema":{"type":"string","enum":["true"]}},{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Production found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/EventBudgetRead"},"cover_crops":{"$ref":"#/components/schemas/CoverCrops","description":"ENG-2785. The series banner framing per surface (listing card, page, Discover). Centered (0.5, 0.5, zoom 1) until the organizer frames it. The series' Discover card uses `discover` whenever the series has its own banner."},"previous_production_id":{"type":["string","null"],"format":"uuid","description":"ENG-2417. The series' previous edition; null when none. Organizer reads only, never on buyer or partner payloads."},"sales_goal_tickets":{"type":["integer","null"],"description":"ENG-2399. Series sales goal in paid tickets; null: none."},"sales_goal_cents":{"type":["integer","null"],"description":"ENG-2399. Series sales goal in gross ticket money (cents); null: none."},"sales_goal_currency":{"type":["string","null"],"description":"ENG-2399. The currency sales_goal_cents was set in (the series' one ticket currency at the time). Null when there is no money goal."},"series_currency":{"type":["string","null"],"description":"ENG-2399. Staff read only. The currency a new money goal would be set in: the one currency the series' ticket and pass types sell in, else (no types yet) the organizer's. Null when they sell in several (a money goal is then refused, 422 sales_goal_currency_unclear)."},"organizer_message":{"type":["string","null"],"description":"ENG-2211. Series message to ticket holders. Null: not set."},"waitlist_join_mode":{"type":["string","null"],"enum":["off","sold_out","always",null],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"walk_up_sales_enabled":{"type":["boolean","null"],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"partner_embed_analytics_enabled":{"type":"boolean","description":"ENG-2307. The series decides for every program in it."},"partner_commerce_pixel_enabled":{"type":"boolean","description":"ENG-2307. The series decides for every program in it."},"cash_at_entry_enabled":{"type":["boolean","null"],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"cash_at_entry_grace_minutes":{"type":["integer","null"]},"cash_at_entry_max_inventory_pct":{"type":["integer","null"]},"custom_questions_set":{"type":"boolean","description":"ENG-2211. True once the series checkout questions were saved; programs then use the series list."},"status":{"$ref":"#/components/schemas/EventStatus","description":"Series status from its shows. `paused` when the organizer paused sales, or when AXYN did (see `sales_paused_reason`). AXYN pauses each on-sale show that needs Stripe; the series then reads `paused` unless another show is still on sale, ahead of sold-out shows (those paused shows still have tickets). Each show's `status` and each type's `on_sale` follow it."},"sales_paused_reason":{"$ref":"#/components/schemas/SalesPausedReason"},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. The series setting. It governs series pass types, and every show that does not set its own value. Never null."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. The series minimum age: 0 (all ages), 18 or 21. Every program follows it unless it has its own. Raising it after tickets or passes are sold is allowed and ticket holders are not notified; tell them yourself."},"lineup_on_series_page":{"type":"boolean","description":"ENG-2337. Whether guests see the series' programs before they buy. False: each entry in `events` keeps its id, status, day, time, place and age, its `title` is the series title, and `hero_image_url`, `program_note` and `who_it_is_for_override` are null; each pass type's `admits[].title` is null. Show no lineup and name no program. Passes and tickets stay on sale. A key that can write the catalog, reading its own series, always receives every program in full."},"ticket_tiers":{"type":"array","items":{"$ref":"#/components/schemas/TicketTier"},"description":"Series catalog read: the day-ticket and pass types on sale. ENG-2341: each pass type carries `claimable_sessions`, the sessions it lets its holder claim, named whatever `lineup_on_series_page` says."},"events":{"type":"array","items":{"$ref":"#/components/schemas/ProductionEventSummary"},"description":"Series catalog read: the shows in this series. Each carries its effective `attendee_details_mode` and its own `attendee_details_mode_override`."}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["catalog"],"summary":"Update production title/description/cover URL/discovery/house rules/who it is for/refund policy (ENG-1648, ENG-1660, ENG-1662, ENG-1663, ENG-1664)","description":"Patches series parent presentation, marketplace visibility, optional House rules, and the Who it is for line. Tenant from API key / staff context. Never from body. Child shows cannot list on Discover. Saving a refund policy writes it through onto every date in the series; the per-date refund editor is refused while an event has a parent series (ENG-1662).","operationId":"updateProduction","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/EventBudgetInput"},"previous_production_id":{"type":["string","null"],"format":"uuid","description":"ENG-2417. The series' previous edition (an earlier series of the same organization); null removes it. Send it alone: with any other field the update is refused whole (400 `previous_edition_alone`). Never set automatically. 422 with `message`: `previous_edition_self`, `previous_edition_loop`, `previous_edition_draft` (no show on sale), `previous_edition_not_held` (its last show hasn't happened), `previous_edition_not_found`. A series whose shows were all cancelled is allowed."},"sales_goal_tickets":{"type":["integer","null"],"minimum":1,"description":"ENG-2399. Optional series sales goal in paid tickets. The Sales forecast's series path climbs to it (\"Path to your goal\"); null clears it (path to sellable capacity)."},"sales_goal_cents":{"type":["integer","null"],"minimum":1,"description":"ENG-2399. Optional series sales goal in gross ticket money (cents, the series' currency). Scales the forecast's gross path; with no tickets goal it also sets the units path at the average live price. Null clears it. Set in the series' currency (series_currency), stamped as sales_goal_currency; refused (422) when the series sells in several."},"sales_goal_currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ENG-2399. Optional, with sales_goal_cents: the currency the form showed the amount in. Refused (422 sales_goal_currency_changed) when the series now sells in another. An unchanged amount keeps its stored currency."},"tax_rate_bps":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Series sales tax in basis points (825 = 8.25%). Copied onto shows with tax_follows_series, so the series' passes are taxed at it. Null with tax_not_applicable null clears it and unlinks every show (they keep their current tax)."},"tax_not_applicable":{"type":["boolean","null"],"description":"True: the series' shows charge no sales tax (clears tax_rate_bps). 400 tax_rate_with_not_applicable when sent true with a rate."},"tax_apply_to_shows":{"type":"boolean","description":"True: link every show in the series to the series tax (tax_follows_series) and copy it in. 400 series_tax_not_set when the series has no tax."},"organizer_message":{"type":["string","null"],"maxLength":500,"description":"ENG-2211. Series message to ticket holders: the one message guests of every program in the series see (a program has none of its own). Null or empty clears it."},"waitlist_join_mode":{"type":"string","enum":["off","sold_out","always"],"description":"ENG-2211. Series waitlist mode, copied onto every program in the series. Null is refused."},"walk_up_sales_enabled":{"type":"boolean","description":"ENG-2211. Sell at the door for the series, copied onto every program in the series."},"cash_at_entry_enabled":{"type":"boolean","description":"ENG-2211. Pay at the door for the series, copied onto every program with its grace and cap. Turning it on (from off or not set) needs a Stripe account that can take charges, as on an event (ENG-2255): 422 pay_at_door_needs_stripe with `blocker`, or 503 payout_check_unavailable."},"cash_at_entry_grace_minutes":{"type":"integer","minimum":1,"description":"ENG-2211. Minutes after each program's start that a pay-at-the-door hold lasts. Defaults to 60 the first time cash_at_entry_enabled is sent. 400 cash_at_entry_enabled_required when sent before the series has chosen on or off."},"cash_at_entry_max_inventory_pct":{"type":"integer","minimum":1,"maximum":100,"description":"ENG-2211. Share of each program's inventory that may be held for pay at the door. Defaults to 20 the first time cash_at_entry_enabled is sent."},"entry_fulfillment_policy":{"type":"string","enum":["digital","will_call","badge"],"description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_requires_scan":{"type":"boolean","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_required_before_admit":{"type":"boolean","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_id_check_required":{"type":"boolean","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_location_label":{"type":["string","null"],"maxLength":200,"description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_address":{"type":["string","null"],"maxLength":300,"description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_instructions":{"type":["string","null"],"maxLength":1000,"description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_opens_at":{"type":["string","null"],"format":"date-time","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_closes_at":{"type":["string","null"],"format":"date-time","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_pickup_reminder_enabled":{"type":"boolean","description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"entry_re_entry_policy":{"type":["string","null"],"enum":["no_reentry","n_times","unlimited",null],"description":"Series pass re-entry default. Null: unlimited (the series rule). Copied onto passes with re_entry_follows_series."},"entry_re_entry_limit":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Series pass default, validated like the event field of the same name. Copied onto passes with the matching *_follows_series flag."},"sales_start_at":{"type":["string","null"],"format":"date-time","description":"When the series' passes go on sale. Null with sales_end_at: while its shows are on sale. Copied onto passes with sales_follow_series (400 tier_sales_window_invalid if it ends before it starts)."},"sales_end_at":{"type":["string","null"],"format":"date-time","description":"When the series' passes stop selling. Copied onto passes with sales_follow_series."},"title":{"type":"string"},"description":{"type":["string","null"]},"hero_image_url":{"type":["string","null"]},"cover_crops":{"$ref":"#/components/schemas/CoverCrops","description":"ENG-2785. The series banner framing, all three surfaces at once. focus_x and focus_y 0 to 1, zoom 1 to 3; anything else is 400 and nothing is saved. A new banner (an upload or a changed hero_image_url) starts centered, as an event cover does, unless cover_crops is sent with it."},"list_on_axyn_discovery":{"type":"boolean"},"partner_embed_analytics_enabled":{"type":"boolean","description":"ENG-2307: Analytics on partner embeds for the series. Copied onto every program; a program cannot set it against its series. Default false."},"partner_commerce_pixel_enabled":{"type":"boolean","description":"ENG-2307: Partner page insights (commerce pixel) for the series. Copied onto every program. Default false."},"house_rules":{"type":["string","null"],"maxLength":8000,"description":"ENG-1664 optional plain-text House rules for this series listing, not the venue."},"getting_in_parking":{"type":["string","null"],"maxLength":200,"description":"Where to park, in one line. Null or blank hides the line on the buyer page."},"getting_in_access":{"type":["string","null"],"maxLength":200,"description":"How to get in when getting in is not obvious (which door, step-free route, ID rules). Null or blank hides the line."},"getting_in_arrival":{"type":["string","null"],"maxLength":200,"description":"When to turn up, in one line. Null or blank hides the line."},"who_it_is_for":{"type":["string","null"],"maxLength":280,"description":"ENG-1663 series default Who it is for line. Null or empty clears it. Not a door check."},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. Series setting: require a name for every ticket. An email per ticket is optional. Shows follow it unless a show sets its own value. Series pass types always follow it. Default off."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. The series minimum age: 0 (all ages), 18 or 21. Every program follows it unless it has its own. Raising it after tickets or passes are sold is allowed and ticket holders are not notified; tell them yourself."},"lineup_on_series_page":{"type":"boolean","description":"ENG-2337. Show the series' programs to guests who do not hold a ticket yet: the series page, checkout and search listings. False hides each program's name, image and description there. Passes and tickets stay on sale either way. A series created through the API starts false."},"lineup_on_live_pass":{"type":"boolean","description":"ENG-2337. Show the programs a pass opens to guests who hold a pass or ticket: the live pass, My Tickets, the wallet pass and emails about their ticket. False hides them there; a session the guest claimed or a seat reserved for them is still shown. Changing it sends no message. Pass confirmation emails never list programs, whatever this is set to. A series created through the API starts false."},"lineup_series_page_reveal_at":{"type":["string","null"],"format":"date-time","description":"ENG-2343. When the series page lineup shows by itself: from this instant guests who do not hold a ticket yet see the programs, as if `lineup_on_series_page` were true, with nothing else to do. An ISO 8601 date-time with an offset (`Z` or `+hh:mm`); null removes it. Refused with 422 `lineup_reveal_in_past` when the time is now or earlier, 422 `lineup_reveal_already_shown` when that lineup is already showing (its switch is on, or an earlier time has come), and 422 `lineup_reveal_conflict` when sent together with `lineup_on_series_page: true`. Sent with `lineup_on_series_page: false` it is saved. Setting `lineup_on_series_page` to true clears it; setting it to false clears it only when it has already come, so a lineup turned off by hand stays off. It never changes `lineup_on_live_pass` or its time. No message is sent to anyone when it comes, and it is never sent to guests."},"lineup_live_pass_reveal_at":{"type":["string","null"],"format":"date-time","description":"ENG-2343. When the live pass lineup shows by itself: from this instant guests who hold a pass or ticket see the programs it opens, as if `lineup_on_live_pass` were true. Same format, rules and error codes as `lineup_series_page_reveal_at`, against `lineup_on_live_pass`. It never changes `lineup_on_series_page` or its time."},"refunds_enabled":{"type":"boolean","description":"ENG-1662 buyer refund policy for the whole series. Written through to every date."},"refund_policy":{"type":"string","enum":["none","window","always","producer_discretion"],"description":"ENG-1662 same presets events use."},"refund_window_hours":{"type":["integer","null"],"minimum":0,"description":"ENG-1662 hours before start that refunds close; null means until start time."}}}}}},"responses":{"200":{"description":"Production updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"cover_crops":{"$ref":"#/components/schemas/CoverCrops","description":"ENG-2785. The series banner framing per surface (listing card, page, Discover). Centered (0.5, 0.5, zoom 1) until the organizer frames it. The series' Discover card uses `discover` whenever the series has its own banner."},"previous_production_id":{"type":["string","null"],"format":"uuid","description":"ENG-2417. The series' previous edition; null when none. Organizer reads only, never on buyer or partner payloads."},"sales_goal_tickets":{"type":["integer","null"],"description":"ENG-2399. Series sales goal in paid tickets; null: none."},"sales_goal_cents":{"type":["integer","null"],"description":"ENG-2399. Series sales goal in gross ticket money (cents); null: none."},"sales_goal_currency":{"type":["string","null"],"description":"ENG-2399. The currency sales_goal_cents was set in (the series' one ticket currency at the time). Null when there is no money goal."},"organizer_message":{"type":["string","null"],"description":"ENG-2211. Series message to ticket holders. Null: not set."},"waitlist_join_mode":{"type":["string","null"],"enum":["off","sold_out","always",null],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"walk_up_sales_enabled":{"type":["boolean","null"],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"cash_at_entry_enabled":{"type":["boolean","null"],"description":"ENG-2211. Null: the series has not set it and each program keeps its own."},"cash_at_entry_grace_minutes":{"type":["integer","null"]},"cash_at_entry_max_inventory_pct":{"type":["integer","null"]},"custom_questions_set":{"type":"boolean","description":"ENG-2211. True once the series checkout questions were saved; programs then use the series list."},"attendee_details_mode":{"type":"string","enum":["off","required"],"description":"ENG-733. The series setting. It governs series pass types, and every show that does not set its own value. Never null."},"minimum_age":{"type":"integer","enum":[0,18,21],"description":"ENG-2300. The series minimum age: 0 (all ages), 18 or 21. Every program follows it unless it has its own. Raising it after tickets or passes are sold is allowed and ticket holders are not notified; tell them yourself."},"lineup_on_series_page":{"type":"boolean","description":"ENG-2337. Guests who do not hold a ticket yet see the series' programs."},"lineup_on_live_pass":{"type":"boolean","description":"ENG-2337. Guests who hold a pass or ticket see the programs it opens."},"lineup_series_page_reveal_at":{"type":["string","null"],"format":"date-time","description":"ENG-2343. The series page reveal time as stored, or null. `lineup_on_series_page` here is the switch as stored: the lineup shows to guests when the switch is true or this time has come. Organizer reads only (staff, or the organizer's own write key); never on a guest read."},"lineup_live_pass_reveal_at":{"type":["string","null"],"format":"date-time","description":"ENG-2343. The live pass reveal time as stored, or null. The lineup shows to pass and ticket holders when `lineup_on_live_pass` is true or this time has come. Organizer reads only; never on a guest read."}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"badge_pickup_locked_by_sales: turning the series badge desk off while a pass that follows it has badge tickets.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"422":{"description":"ENG-2343. A lineup reveal time was refused and nothing was saved. `error` and `code` both carry one of: `lineup_reveal_in_past` (the time is now or earlier), `lineup_reveal_already_shown` (that lineup is already showing), `lineup_reveal_conflict` (sent with its switch set to true). sales_goal_currency_unclear: a money goal on a series whose ticket types sell in several currencies; sales_goal_currency_changed: the amount was entered in a currency the series no longer sells in. A goal refusal saves nothing else from the PATCH.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"code":{"type":"string","enum":["lineup_reveal_in_past","lineup_reveal_already_shown","lineup_reveal_conflict"]}}}}}}}}},"/v1/productions/{productionId}/lineup-preview":{"get":{"tags":["catalog"],"summary":"Preview what guests see of the series lineup","description":"Organizer only (catalog write scope). Reads only: nothing is saved, sent or issued. `series_page` returns the guest read of the series, exactly as `GET /v1/productions/{productionId}` sends it to a guest. `live_pass` returns a sample live pass for one pass type, built for no ticket: it carries no ticket, order, guest name, email or entry code. `when=after_reveal` reads the same surface at its scheduled reveal time, so the organizer sees the announced page before guests do; when the lineup already shows it is the same as `now`.","operationId":"getSeriesLineupPreview","security":[{"tenantApiKey":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"surface","in":"query","required":true,"schema":{"type":"string","enum":["series_page","live_pass"]}},{"name":"when","in":"query","required":false,"schema":{"type":"string","enum":["now","after_reveal"],"default":"now"}},{"name":"pass_tier_id","in":"query","required":false,"description":"`live_pass` only: the pass type to sample. Left out: the series' first active pass type by its order.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The preview and the state it was read in.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SeriesLineupPreview"}}}}}},"400":{"description":"Unknown `surface` or `when`, or `productionId` / `pass_tier_id` is not a UUID."},"401":{"description":"Tenant API key or staff sign-in required."},"403":{"description":"The key lacks the catalog write scope."},"404":{"description":"No such series for this organizer.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["production_not_found"]},"code":{"type":"string","enum":["production_not_found"]}}}}}},"422":{"description":"`lineup_preview_no_reveal`: `after_reveal` was asked for a surface whose lineup is hidden with no reveal time set. `lineup_preview_no_pass`: the series has no active pass type, or `pass_tier_id` is not one of its pass types.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["lineup_preview_no_reveal","lineup_preview_no_pass"]},"code":{"type":"string","enum":["lineup_preview_no_reveal","lineup_preview_no_pass"]}}}}}}}}},"/v1/productions/{productionId}/custom-questions":{"get":{"tags":["catalog"],"summary":"List the series checkout questions","operationId":"listSeriesCustomQuestions","security":[{"tenantApiKey":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The series questions and the programs not on them. A program whose questions already have answers keeps them.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"set":{"type":"boolean","description":"False until the series list is saved once; until then every program keeps its own questions."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/EventCustomQuestion"}},"programs_keeping_own":{"type":"array","description":"Programs whose checkout questions are not the series list: their own questions already have answers, so they were not rewritten.","items":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["catalog"],"summary":"Replace the series checkout questions and copy them onto its programs","operationId":"replaceSeriesCustomQuestions","security":[{"tenantApiKey":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["questions"],"properties":{"questions":{"type":"array","maxItems":8,"items":{"type":"object","required":["prompt","answer_kind","is_required","grain","options"],"properties":{"prompt":{"type":"string","maxLength":500},"answer_kind":{"type":"string","enum":["short_text","long_text","single_select","multi_select","yes_no","acknowledgment"],"description":"`acknowledgment` is a box the guest must tick to agree to `prompt`: always saved required, with no options."},"is_required":{"type":"boolean"},"grain":{"type":"string","enum":["per_order","per_ticket"]},"options":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":120}}}},"show_ids":{"type":"array","nullable":true,"minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"},"description":"ENG-3338: limit the question to these programs of the series (event ids). Absent or null asks every buyer. An empty list is refused with `Pick at least one show`; a show outside the series with `custom_question_show_not_in_series`."}}}}}}}}},"responses":{"200":{"description":"The series questions and the programs not on them. A program whose questions already have answers keeps them.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"set":{"type":"boolean","description":"False until the series list is saved once; until then every program keeps its own questions."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/EventCustomQuestion"}},"programs_keeping_own":{"type":"array","description":"Programs whose checkout questions are not the series list: their own questions already have answers, so they were not rewritten.","items":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"title":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/productions/{productionId}/events":{"get":{"tags":["catalog"],"summary":"List sibling occurrences for a production (ENG-1558)","description":"Returns tenant events linked to the production, ordered by starts_at. M46c dual-auth: API key catalog:read or staff JWT event.read + x-tenant-id. API key reads list on_sale and sold_out shows. With include_drafts=true they also list draft shows when the key belongs to the organizer that owns the series (draft integration, opt-in). Another organizer's key and the hosted shop never see a draft; for them the parameter is ignored.","operationId":"listProductionEvents","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"include_drafts","in":"query","required":false,"description":"Draft integration opt-in. `true` adds the series' draft shows (and their types) when the API key belongs to the organizer that owns the series and the call is not the hosted shop. Ignored otherwise; drafts never sell.","schema":{"type":"string","enum":["true"]}},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TenantIdHeader"}],"responses":{"200":{"description":"Occurrence events in this production.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ProductionEventSummary"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["catalog"],"summary":"Link an occurrence event to a production (ENG-138 minimal)","description":"Sets event.production_id for a tenant-owned event. Missing production or event collapses to opaque 404. The show loses its previous edition (`previous_event_id`) and every other event's link to it (ENG-2417 Q-A8). If removing the links to it fails, the show is still linked to the series, on its passes, and the answer is 500 `previous_edition_clear_failed`: send the same call again, or save the show, to finish.","operationId":"linkEventToProduction","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TenantIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id"],"properties":{"event_id":{"type":"string","format":"uuid"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Event linked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"},"description":"pass_coverage_skipped: the show joined the series but could not join one of its Every show / By day passes (e.g. a reserved-seat show whose pass already has holders, or a show with no place yet, which joins once it gets one)."},"data":{"$ref":"#/components/schemas/Event"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/productions/{productionId}/cover":{"post":{"tags":["catalog"],"summary":"Upload production cover art (ENG-1648)","description":"Multipart JPEG/PNG/WebP (<=5 MiB) stores under event-covers using production id as the object path entity and writes production.hero_image_url. Same pipeline as event covers.","operationId":"uploadProductionCover","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Cover uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"hero_image_url":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"description":"Cover storage unavailable"}}}},"/v1/productions/{productionId}/gallery":{"get":{"tags":["productions"],"summary":"Read the series listing gallery","operationId":"readSeriesListingGallery","description":"ENG-1667 — the listing mosaic (images plus allowlisted video) an organizer edits. A listing is a series or an independent event; a child show has no gallery of its own.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gallery items in display order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListingGalleryItem"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["productions"],"summary":"Replace the series listing gallery","operationId":"replaceSeriesListingGallery","description":"ENG-1667 — replaces the whole gallery. Array order is the order guests see. Send an empty array to clear it. Up to 12 items. Every image_url must be one AXYN stored for this tenant.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/ListingGalleryItemWrite"}}}}}}},"responses":{"200":{"description":"Gallery saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListingGalleryItem"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/productions/{productionId}/gallery/images":{"post":{"tags":["productions"],"summary":"Upload one series listing gallery photo","operationId":"uploadSeriesListingGalleryImage","description":"ENG-1667 — store a JPEG/PNG/WebP (5 MiB or smaller, 4096 px or fewer on the long edge) and return its URL plus intrinsic size. Magic-byte sniff; the client Content-Type is ignored. Send the returned image_url back in the gallery PUT.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP. 5 MiB or smaller."}}}}}},"responses":{"200":{"description":"Photo stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"image_url":{"type":"string","format":"uri"},"width_px":{"type":"integer"},"height_px":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"description":"Gallery object store is not configured or the put failed"}}}},"/v1/events/{eventId}/gallery":{"get":{"tags":["event-lifecycle"],"summary":"Read the event listing gallery","operationId":"readEventListingGallery","description":"ENG-1667 — the listing mosaic (images plus allowlisted video) an organizer edits. A listing is a series or an independent event; a child show has no gallery of its own.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gallery items in display order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListingGalleryItem"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"series_gallery_is_production_scoped — this event is a child show. The response data carries the production_id whose gallery to edit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","example":"series_gallery_is_production_scoped"},"data":{"type":"object","properties":{"production_id":{"type":"string","format":"uuid","nullable":true}}}}}}}}}},"put":{"tags":["event-lifecycle"],"summary":"Replace the event listing gallery","operationId":"replaceEventListingGallery","description":"ENG-1667 — replaces the whole gallery. Array order is the order guests see. Send an empty array to clear it. Up to 12 items. Every image_url must be one AXYN stored for this tenant.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/ListingGalleryItemWrite"}}}}}}},"responses":{"200":{"description":"Gallery saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListingGalleryItem"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"series_gallery_is_production_scoped — this event is a child show. The response data carries the production_id whose gallery to edit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","example":"series_gallery_is_production_scoped"},"data":{"type":"object","properties":{"production_id":{"type":"string","format":"uuid","nullable":true}}}}}}}}}}},"/v1/events/{eventId}/gallery/images":{"post":{"tags":["event-lifecycle"],"summary":"Upload one event listing gallery photo","operationId":"uploadEventListingGalleryImage","description":"ENG-1667 — store a JPEG/PNG/WebP (5 MiB or smaller, 4096 px or fewer on the long edge) and return its URL plus intrinsic size. Magic-byte sniff; the client Content-Type is ignored. Send the returned image_url back in the gallery PUT.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, or WebP. 5 MiB or smaller."}}}}}},"responses":{"200":{"description":"Photo stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"image_url":{"type":"string","format":"uri"},"width_px":{"type":"integer"},"height_px":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"series_gallery_is_production_scoped — this event is a child show. The response data carries the production_id whose gallery to edit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","example":"series_gallery_is_production_scoped"},"data":{"type":"object","properties":{"production_id":{"type":"string","format":"uuid","nullable":true}}}}}}}},"503":{"description":"Gallery object store is not configured or the put failed"}}}},"/v1/events/{eventId}/claimable-session":{"get":{"tags":["catalog"],"summary":"Read the claim-from-pass panel for one session","operationId":"getEventClaimableSession","description":"Claim mode, capacity, window, price and the pass types that unlock this session.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Claim panel.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"claimable_session":{"$ref":"#/components/schemas/ClaimableSession"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["catalog"],"summary":"Create or edit the claim-from-pass panel for one session","operationId":"putEventClaimableSession","description":"Safe while selling. The claim block is checked against the occurrence capacity ceiling, capacity may only shrink to claims already held, and dropping a pass type closes future claims without stripping claims already made.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_mode","claim_capacity","eligible_pass_tier_ids"],"properties":{"claim_mode":{"type":"string","enum":["must_claim","optional_rsvp"]},"claim_capacity":{"type":"integer","minimum":0},"eligible_pass_tier_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"price_cents":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"max_claims_per_pass":{"type":"integer","minimum":1},"claim_opens_at":{"type":"string","format":"date-time","nullable":true},"claim_closes_at":{"type":"string","format":"date-time","nullable":true},"release_closes_at":{"type":"string","format":"date-time","nullable":true},"guest_note":{"type":"string","maxLength":200,"nullable":true}}}}}},"responses":{"200":{"description":"Saved claim panel.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"claimable_session":{"$ref":"#/components/schemas/ClaimableSession"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"description":"Capacity could not be read; the write was refused."}}},"delete":{"tags":["catalog"],"summary":"Stop taking new claims on this session","operationId":"deleteEventClaimableSession","description":"Claims already held keep their place and keep admitting at the door.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Claiming closed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"disabled":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/tiers/{tierId}/claimable-sessions":{"get":{"tags":["catalog"],"summary":"List the sessions one pass type unlocks","operationId":"listPassTierClaimableSessions","description":"Read-only. Capacity and mode are edited on the session itself.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sessions this pass unlocks.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"claimable_session_id":{"type":"string","format":"uuid"},"occurrence_event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time","nullable":true},"timezone":{"type":"string","nullable":true},"claim_mode":{"type":"string","enum":["must_claim","optional_rsvp"]},"is_enabled":{"type":"boolean"},"price_cents":{"type":"integer","minimum":0},"session_price_cents":{"type":"integer","minimum":0,"description":"The session's own price: what a pass with no price of its own pays."},"pass_price_cents":{"type":["integer","null"],"minimum":0,"description":"This pass's price for the session. Null follows the session price; 0 is included. price_cents is the one this pass pays."},"currency":{"type":"string"},"claims_remaining":{"type":"integer","minimum":0}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/events/tiers/{tierId}/claimable-sessions/{sessionId}":{"patch":{"tags":["catalog"],"summary":"Set what one pass pays to claim a session","operationId":"setPassTierClaimableSessionPrice","description":"price_cents null follows the session's own price; 0 is included with this pass. Claims already held keep the price they paid. Returns the pass's sessions.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"tierId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price_cents"],"properties":{"price_cents":{"type":["integer","null"],"minimum":0,"maximum":99999999}},"additionalProperties":false}}}},"responses":{"200":{"description":"The pass's sessions, with the new price.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"claimable_session_id":{"type":"string","format":"uuid"},"occurrence_event_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time","nullable":true},"timezone":{"type":"string","nullable":true},"claim_mode":{"type":"string","enum":["must_claim","optional_rsvp"]},"is_enabled":{"type":"boolean"},"price_cents":{"type":"integer","minimum":0},"session_price_cents":{"type":"integer","minimum":0,"description":"The session's own price: what a pass with no price of its own pays."},"pass_price_cents":{"type":["integer","null"],"minimum":0,"description":"This pass's price for the session. Null follows the session price; 0 is included. price_cents is the one this pass pays."},"currency":{"type":"string"},"claims_remaining":{"type":"integer","minimum":0}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"claimable_session_not_found: the session is not one this pass can claim."}}}},"/v1/ticket-url/{token}/claimable-sessions":{"get":{"tags":["claims","public"],"summary":"List sessions this Live Pass can claim","operationId":"listTicketUrlClaimableSessions","description":"Ticket-url bearer proves holdership; no buyer JWT. Every miss is the same opaque 404.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Claimable sessions and how many claims are left.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"claims_left":{"type":"integer","minimum":0},"max_claims_per_pass":{"type":"integer","minimum":1},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ClaimableSessionOffer"}}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ticket-url/{token}/claims":{"post":{"tags":["claims","public"],"summary":"Claim a session onto this Live Pass","operationId":"createTicketUrlSessionClaim","description":"Free claims land immediately. A paid claim reserves the seat and returns a Stripe client secret; the session attaches to the same Live Pass once the charge succeeds. No second QR is ever minted.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claimable_session_id"],"properties":{"claimable_session_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Claim held.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"claim_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["claimed","pending_payment"]},"price_cents":{"type":"integer","minimum":0},"charged_cents":{"type":"integer","minimum":0,"description":"What the card is debited: face price plus the card fee this second charge owes. Equals price_cents when free."},"currency":{"type":"string"},"payment_intent_id":{"type":"string"},"client_secret":{"type":"string","nullable":true},"stripe_connect_account_id":{"type":["string","null"],"description":"Connected Stripe account the PaymentIntent lives on (direct charge). Pass it to Stripe.js as stripeAccount. Null when the intent is on the platform (sandbox tenants, test mode)."},"stripe_publishable_key":{"type":["string","null"],"description":"Stripe publishable key for the mode the PaymentIntent was opened in (test for a sandbox tenant). Mount Stripe.js with this key, not a site env key."},"wallets":{"$ref":"#/components/schemas/CheckoutWallets"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/PaymentGatewayError"}}}},"/v1/ticket-url/{token}/claims/{claimId}":{"delete":{"tags":["claims","public"],"summary":"Hand a claimed session back","operationId":"deleteTicketUrlSessionClaim","description":"Releases the seat while the organizer's release window is open. A paid claim is refunded first, and the session leaves this Live Pass.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"claimId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Claim released.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"claim_id":{"type":"string","format":"uuid"}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/TicketUrlRetired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/PaymentGatewayError"}}}},"/v1/events/{eventId}/accreditation":{"get":{"tags":["accreditation"],"operationId":"getAccreditationSummary","summary":"Accreditation tab summary","description":"Enabled classes and applications awaiting a decision (pending + waitlisted). Drives tab visibility and its badge.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"enabled_classes":{"type":"integer"},"open_applications":{"type":"integer"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/events/{eventId}/accreditation-classes":{"get":{"tags":["accreditation"],"operationId":"listAccreditationClasses","summary":"List accreditation classes","description":"Classes with form, counts, capacity and copyable apply link.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"classes":{"type":"array","items":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"post":{"tags":["accreditation"],"operationId":"createAccreditationClass","summary":"Create an accreditation class","description":"Binds a hidden ticket type. Result codes: tier_not_found, tier_not_hidden, hold_not_found, duplicate_class_name, class_limit_reached, invalid_*.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccreditationClassInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/events/{eventId}/accreditation-classes/{classId}":{"get":{"tags":["accreditation"],"operationId":"getAccreditationClass","summary":"Get an accreditation class","description":"","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"patch":{"tags":["accreditation"],"operationId":"updateAccreditationClass","summary":"Update an accreditation class","description":"Partial update. Closing or disabling stops new submits; open applications stay decidable. Result codes: tier_locked (a pass was issued), question_locked (answered question kind/options changed or removed).","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccreditationClassInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}},"delete":{"tags":["accreditation"],"operationId":"deleteAccreditationClass","summary":"Delete an accreditation class","description":"Only while nobody has applied (class_has_applications). Otherwise disable it.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/events/{eventId}/accreditation-classes/{classId}/rotate-link":{"post":{"tags":["accreditation"],"operationId":"rotateAccreditationApplyLink","summary":"Replace the apply link","description":"The old link stops accepting submits immediately. Existing applications are unaffected.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/events/{eventId}/accreditation-applications":{"get":{"tags":["accreditation"],"operationId":"listAccreditationApplications","summary":"List applications","description":"Newest first, with answers. Cursor-paginated.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"class_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list, e.g. `pending,waitlisted`."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search name, email, organization or reference."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/AccreditationApplication"}},"next_cursor":{"type":"string","nullable":true},"total":{"type":"integer"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/events/{eventId}/accreditation-applications/export":{"get":{"tags":["accreditation"],"operationId":"exportAccreditationApplications","summary":"Export applications as CSV","description":"Same filters as the list; one column per question. Cells that could run as spreadsheet formulas are quoted.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"class_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list, e.g. `pending,waitlisted`."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search name, email, organization or reference."}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/events/{eventId}/accreditation-applications/decisions":{"post":{"tags":["accreditation"],"operationId":"bulkDecideAccreditationApplications","summary":"Approve, deny or waitlist many","description":"Up to 100, applied in order, each on its own. Approvals past the class cap report class_capacity_reached.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","application_ids"],"properties":{"action":{"type":"string","enum":["approve","deny","waitlist"]},"application_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"applicant_message":{"type":"string","nullable":true,"maxLength":1000}}}}}},"responses":{"200":{"description":"Per-application results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"application_id":{"type":"string","format":"uuid"},"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid","nullable":true}}}}}}}}}}},"400":{"description":"Invalid input"}}}},"/v1/events/{eventId}/accreditation-applications/{applicationId}":{"get":{"tags":["accreditation"],"operationId":"getAccreditationApplication","summary":"Get an application","description":"Answers, internal notes and the decision trail.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"patch":{"tags":["accreditation"],"operationId":"updateAccreditationApplicationEmail","summary":"Fix the applicant email","description":"Only while pending or waitlisted. The new address gets a fresh status link; old links stop working.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicant_email"],"properties":{"applicant_email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/events/{eventId}/accreditation-applications/{applicationId}/decision":{"post":{"tags":["accreditation"],"operationId":"decideAccreditationApplication","summary":"Approve, deny, waitlist or revoke","description":"approve issues exactly one Live Pass (no payment, no coupon, no card check). deny/waitlist/revoke email the applicant. revoke voids the pass and needs a signed-in staff user (staff_user_required). Result codes: already_approved, not_decidable, not_approved, class_capacity_reached, insufficient_hold_balance, insufficient_inventory, tier_not_active (the class's ticket type was archived or turned off), applicant_erased, ticket_already_redeemed.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","deny","waitlist","revoke"]},"applicant_message":{"type":"string","nullable":true,"maxLength":1000,"description":"Shown to the applicant."},"internal_note":{"type":"string","nullable":true,"maxLength":1000,"description":"Staff only."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"},"ticket_id":{"type":"string","format":"uuid","nullable":true}}}}}}}},"400":{"description":"Invalid input"},"403":{"description":"A signed-in staff user is required"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/events/{eventId}/accreditation-applications/{applicationId}/notes":{"post":{"tags":["accreditation"],"operationId":"addAccreditationApplicationNote","summary":"Add an internal note","description":"Staff only. Never shown to the applicant.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/productions/{productionId}/accreditation":{"get":{"tags":["accreditation"],"operationId":"getAccreditationSummaryForSeries","summary":"Accreditation tab summary","description":"Enabled classes and applications awaiting a decision (pending + waitlisted). Drives tab visibility and its badge.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"enabled_classes":{"type":"integer"},"open_applications":{"type":"integer"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/productions/{productionId}/accreditation-classes":{"get":{"tags":["accreditation"],"operationId":"listAccreditationClassesForSeries","summary":"List accreditation classes","description":"Classes with form, counts, capacity and copyable apply link.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"classes":{"type":"array","items":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"post":{"tags":["accreditation"],"operationId":"createAccreditationClassForSeries","summary":"Create an accreditation class","description":"Binds a hidden ticket type. Result codes: tier_not_found, tier_not_hidden, hold_not_found, duplicate_class_name, class_limit_reached, invalid_*.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccreditationClassInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/productions/{productionId}/accreditation-classes/{classId}":{"get":{"tags":["accreditation"],"operationId":"getAccreditationClassForSeries","summary":"Get an accreditation class","description":"","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"patch":{"tags":["accreditation"],"operationId":"updateAccreditationClassForSeries","summary":"Update an accreditation class","description":"Partial update. Closing or disabling stops new submits; open applications stay decidable. Result codes: tier_locked (a pass was issued), question_locked (answered question kind/options changed or removed).","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccreditationClassInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}},"delete":{"tags":["accreditation"],"operationId":"deleteAccreditationClassForSeries","summary":"Delete an accreditation class","description":"Only while nobody has applied (class_has_applications). Otherwise disable it.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/productions/{productionId}/accreditation-classes/{classId}/rotate-link":{"post":{"tags":["accreditation"],"operationId":"rotateAccreditationApplyLinkForSeries","summary":"Replace the apply link","description":"The old link stops accepting submits immediately. Existing applications are unaffected.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"classId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/AccreditationClass"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/productions/{productionId}/accreditation-applications":{"get":{"tags":["accreditation"],"operationId":"listAccreditationApplicationsForSeries","summary":"List applications","description":"Newest first, with answers. Cursor-paginated.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"class_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list, e.g. `pending,waitlisted`."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search name, email, organization or reference."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/AccreditationApplication"}},"next_cursor":{"type":"string","nullable":true},"total":{"type":"integer"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/productions/{productionId}/accreditation-applications/export":{"get":{"tags":["accreditation"],"operationId":"exportAccreditationApplicationsForSeries","summary":"Export applications as CSV","description":"Same filters as the list; one column per question. Cells that could run as spreadsheet formulas are quoted.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"class_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list, e.g. `pending,waitlisted`."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search name, email, organization or reference."}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/productions/{productionId}/accreditation-applications/decisions":{"post":{"tags":["accreditation"],"operationId":"bulkDecideAccreditationApplicationsForSeries","summary":"Approve, deny or waitlist many","description":"Up to 100, applied in order, each on its own. Approvals past the class cap report class_capacity_reached.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","application_ids"],"properties":{"action":{"type":"string","enum":["approve","deny","waitlist"]},"application_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"applicant_message":{"type":"string","nullable":true,"maxLength":1000}}}}}},"responses":{"200":{"description":"Per-application results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"application_id":{"type":"string","format":"uuid"},"result_code":{"type":"string"},"ticket_id":{"type":"string","format":"uuid","nullable":true}}}}}}}}}}},"400":{"description":"Invalid input"}}}},"/v1/productions/{productionId}/accreditation-applications/{applicationId}":{"get":{"tags":["accreditation"],"operationId":"getAccreditationApplicationForSeries","summary":"Get an application","description":"Answers, internal notes and the decision trail.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"}}}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}},"patch":{"tags":["accreditation"],"operationId":"updateAccreditationApplicationEmailForSeries","summary":"Fix the applicant email","description":"Only while pending or waitlisted. The new address gets a fresh status link; old links stop working.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicant_email"],"properties":{"applicant_email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/productions/{productionId}/accreditation-applications/{applicationId}/decision":{"post":{"tags":["accreditation"],"operationId":"decideAccreditationApplicationForSeries","summary":"Approve, deny, waitlist or revoke","description":"approve issues exactly one Live Pass (no payment, no coupon, no card check). deny/waitlist/revoke email the applicant. revoke voids the pass and needs a signed-in staff user (staff_user_required). Result codes: already_approved, not_decidable, not_approved, class_capacity_reached, insufficient_hold_balance, insufficient_inventory, tier_not_active (the class's ticket type was archived or turned off), applicant_erased, ticket_already_redeemed.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","deny","waitlist","revoke"]},"applicant_message":{"type":"string","nullable":true,"maxLength":1000,"description":"Shown to the applicant."},"internal_note":{"type":"string","nullable":true,"maxLength":1000,"description":"Staff only."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AccreditationApplicationDetail"},"ticket_id":{"type":"string","format":"uuid","nullable":true}}}}}}}},"400":{"description":"Invalid input"},"403":{"description":"A signed-in staff user is required"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"}}}},"/v1/productions/{productionId}/accreditation-applications/{applicationId}/notes":{"post":{"tags":["accreditation"],"operationId":"addAccreditationApplicationNoteForSeries","summary":"Add an internal note","description":"Staff only. Never shown to the applicant.","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"}}}},"/v1/accreditation/apply/{applyToken}":{"get":{"tags":["accreditation","public"],"operationId":"getAccreditationForm","summary":"Apply form for a link","description":"No API key. The apply link is the credential. Unknown, rotated or foreign tokens (coupon codes, access codes, allocation links) are 404.","security":[],"parameters":[{"name":"applyToken","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"$ref":"#/components/schemas/AccreditationPublicForm"}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"429":{"description":"Rate limited"}}}},"/v1/accreditation/apply/{applyToken}/applications":{"post":{"tags":["accreditation","public"],"operationId":"submitAccreditationApplication","summary":"Submit an application","description":"No API key. Returns reference_code and a status_token (keep it; send it as X-Accreditation-Status-Token). A second submit by the same email while pending/waitlisted/approved returns already_submitted with the same reference and emails the status link to that address. Rate limited per IP and per email.","security":[],"parameters":[{"name":"applyToken","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicant_name","applicant_email"],"properties":{"applicant_name":{"type":"string","maxLength":200},"applicant_email":{"type":"string","format":"email"},"applicant_organization":{"type":"string","nullable":true,"maxLength":200},"answers":{"type":"array","items":{"type":"object","required":["question_id"],"properties":{"question_id":{"type":"string","format":"uuid"},"answer_text":{"type":"string"},"option_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}}}}},"responses":{"200":{"description":"already_submitted"},"201":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"type":"object","properties":{"reference_code":{"type":"string"},"status_token":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Invalid input"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"},"429":{"description":"Rate limited"}}}},"/v1/accreditation/applications/{reference}":{"get":{"tags":["accreditation","public"],"operationId":"getAccreditationApplicationStatus","summary":"Application status","description":"Requires the status token header. Wrong token, wrong reference and missing application are the same 404.","security":[],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Accreditation-Status-Token","in":"header","required":true,"schema":{"type":"string"},"description":"The status token from submit or from the status link email."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result_code":{"type":"string"},"data":{"$ref":"#/components/schemas/AccreditationPublicStatus"}}}}}},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"429":{"description":"Rate limited"}}}},"/v1/accreditation/applications/{reference}/withdraw":{"post":{"tags":["accreditation","public"],"operationId":"withdrawAccreditationApplication","summary":"Withdraw an application","description":"Pending or waitlisted only.","security":[],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Accreditation-Status-Token","in":"header","required":true,"schema":{"type":"string"},"description":"The status token from submit or from the status link email."}],"responses":{"200":{"description":"Withdrawn"},"404":{"description":"Not found (also wrong tenant, rotated link, or bad status token)"},"409":{"description":"Conflict: see `error` result code"},"429":{"description":"Rate limited"}}}},"/v1/accreditation/status-link":{"post":{"tags":["accreditation","public"],"operationId":"requestAccreditationStatusLink","summary":"Email me my status link","description":"Always 202 whether or not the address applied. The link goes only to the address on file. Send reference_code, or the apply_token of the class.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicant_email"],"properties":{"applicant_email":{"type":"string","format":"email"},"reference_code":{"type":"string"},"apply_token":{"type":"string"}}}}}},"responses":{"202":{"description":"Accepted"},"429":{"description":"Rate limited"}}}},"/v1/productions/{productionId}/coupons":{"get":{"tags":["catalog"],"summary":"List series discounts (codes and automatic) and the series' ticket types (ENG-1888; catalog:write or event.write).","operationId":"listSeriesCoupons","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Coupons.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"coupons":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"}},"ticket_tiers":{"type":"array","items":{"$ref":"#/components/schemas/DiscountScopeTier"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"failed to load coupons"}}},"post":{"tags":["catalog"],"summary":"Create a series discount: a code unique across the series and its shows, or an automatic quantity discount that may cover passes (ENG-1888).","operationId":"createSeriesCoupon","security":[{"bearerAuth":[]},{"tenantApiKey":[]},{"bearerAuth":[],"tenantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantIdHeader"},{"name":"productionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","maxLength":64,"description":"Trimmed and uppercased server-side; no whitespace. Unique among active codes per event (case-insensitive)."},"percent_bps":{"type":"integer","minimum":1,"maximum":9500,"description":"Percent-off in basis points; max 9500 (95%). Provide exactly one of percent_bps / amount_cents."},"amount_cents":{"type":"integer","minimum":1,"description":"Fixed amount off in cents. Provide exactly one of percent_bps / amount_cents."},"apply_mode":{"type":"string","enum":["cart_ticket_subtotal","per_ticket"],"default":"cart_ticket_subtotal","description":"Fixed-amount apply mode. Default cart_ticket_subtotal. per_ticket requires amount_cents and multiplies by ticket qty at redemption."},"max_redemptions":{"type":"integer","minimum":1,"description":"Codes: required, total orders that may redeem. Automatic: optional; omit for unlimited."},"max_discounted_tickets":{"type":"integer","minimum":1,"description":"Codes only: at most this many tickets per order get the discount, the cheapest paid ones first; the rest pay full price. Omit for every eligible ticket. An order still counts as one use."},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","description":"Must be after starts_at when both are set."},"redemption_mode":{"type":"string","enum":["code","automatic"],"default":"code"},"display_name":{"type":"string","minLength":1,"maxLength":60},"quantity_mode":{"type":"string","enum":["per_group","threshold"]},"min_quantity":{"type":"integer","minimum":2,"maximum":50},"group_price_cents":{"type":"integer","minimum":0,"description":"per_group only; must be less than min_quantity x the price of every covered ticket type."},"tier_ids":{"type":"array","maxItems":200,"items":{"type":"string","format":"uuid"},"description":"Ticket types to cover (in scope only; a show scope never lists passes). Empty = all."}},"description":"Code mode (default): code + max_redemptions required, one of percent_bps / amount_cents. Automatic mode (redemption_mode=automatic): display_name, quantity_mode, min_quantity and exactly one of percent_bps / amount_cents / group_price_cents required; no code; max_redemptions optional (empty = unlimited). Refusals are 400 with `field` naming the input."}}}},"responses":{"201":{"description":"Coupon created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"coupon":{"$ref":"#/components/schemas/Coupon"},"warnings":{"type":"array","items":{"type":"string","enum":["below_order_floor"]},"description":"Non-blocking: a covered ticket type would price an order under the $5 floor, so the discount is reduced there."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"coupon_code_exists, or coupon_code_in_use when the code is active on the series or one of its shows (`detail` says where)."}}}}}}