25 "decision": "Create with { ticketDefinition: { eventId, name, pricingMethod, feeType, initialLimit?, hidden? } }. eventId, name, pricingMethod and feeType are all required. Verified live on a DRAFT event, so definitions can be staged before the event is published; hidden:true keeps a definition unpurchasable. DELETE /events/v3/ticket-definitions/{id} works. Max 100 definitions per event."
26 },
27 "reliability": {
28 "status": "reliable",
29 "flags": []
30 },
31 "pitfalls": [
32 {
33 "code": "definitions-not-sales",
34 "severity": "blocker",
35 "summary": "A ticket definition is the purchasable ticket type (name, price, limits) — importing it does not carry sold tickets. Past ticket sales remain not importable (domain pitfall ticket-order-history-not-importable)."
36 },
37 {
38 "code": "past-event-definitions-unverified",
39 "severity": "warning",
40 "summary": "VERIFIED LIVE 2026-10-27: free (NO_FEE) and paid (FEE_INCLUDED) definitions are accepted on an ended (past) ticketing event and read back."
41 },
42 {
43 "code": "ticketing-events-only",
44 "severity": "blocker",
45 "summary": "Create fails with 428 INVALID_EVENT_TYPE unless the event's registration.initialType is TICKETING, and initialType is IMMUTABLE (docs) — an event created for RSVP can never take ticket definitions. Decide RSVP vs TICKETING at event-create time from the source data; a source event with both attendee lists and ticket types cannot be represented as one Wix event."
46 },
47 {
48 "code": "name-capped-at-30-chars",
49 "severity": "warning",
50 "summary": "`name` is minLength 1 / maxLength 30 (description 500, policyText 1000). Source ticket-type names routinely exceed 30 characters — truncate deterministically and ledger it rather than letting the create 400."
51 },
52 {
53 "code": "free-ticket-fee-type",
54 "severity": "warning",
55 "summary": "VERIFIED LIVE 2026-08-16: a free ticket is pricingMethod.fixedPrice.value \"0\" plus feeType NO_FEE (the response echoes free:true, pricingType STANDARD, value normalised to \"0.00\"). NO_FEE is only accepted for free tickets and legacy users — paid tickets must pick FEE_INCLUDED or FEE_ADDED_AT_CHECKOUT, a merchant decision that belongs in the mapping review, not a default."
56 },
57 {
58 "code": "canonical-vs-alias-path",
59 "severity": "warning",
60 "summary": "The docs canonical host path is /events-ticket-definitions/v3/ticket-definitions; /events/v3/ticket-definitions is an accepted alias (both returned 200 on 2026-08-16, creating one definition each). They are the same resource — do not call both in one import or you double-create."
61 },
62 {
63 "code": "paid-fee-from-source-or-review",
64 "severity": "warning",
65 "summary": "Owner decision (2026-10-27): copy the fee mode and ticket tax from the source when it has them; otherwise the mapper adds one mapping-review choice before consent with FEE_INCLUDED pre-selected. The builder refuses a paid ticket without feeType, so no default is applied silently."
66 }
67 ],
68 "mappingGuidance": [
69 "Dependencies: events/event is required because ticketDefinition.eventId identifies the event that owns every ticket definition.",
70 "Create the event first with registration.initialType TICKETING and use its crosswalked ID in eventId; ticket definitions are per-event and initialType cannot be changed later.",
71 "Map source ticket types (e.g. Event Tickets ticket name/price/capacity) to name (≤30 chars), pricingMethod.fixedPrice (or pricingOptions for tiered prices, guestPrice for pay-what-you-want) and initialLimit; omit initialLimit for unlimited tickets.",
72 "Set salePeriod from the source sale window when present (startDate before endDate, else 428 INVALID_SALE_PERIOD); use hidden:true to stage definitions that should not go on sale at import time."
91 "note": "The docs survey identified the ticket-definition surface."
92 },
93 {
94 "type": "live-run",
95 "path": "anonymized-live-verification",
96 "note": "Verified live: a free hidden ticket definition can be created on a future draft ticketing event through both the /events/v3 alias and the canonical /events-ticket-definitions/v3 path and read back successfully. Probe records were deleted afterward."
97 },
98 {
99 "type": "live-run",
100 "path": "anonymized-live-verification",
101 "note": "Verified live 2026-10-27 on a throwaway site created for the probe (notifications muted): create, read back, query, past dates, category assignment."
102 }
103 ],
104 "notes": "Authored 2026-08-11 from the docs-survey gap (Ticket Definitions V3). Promoted to verified-live 2026-08-16 by a create/read/delete probe on a draft ticketing event; the probe also pinned the required feeType, the 30-char name cap, and the TICKETING-only/immutable-initialType constraint.",