15 "summary": "The Events Calendar's `event` entity can map to either Wix Events (events/event) or a Wix Bookings Service (bookings/service, type CLASS) — they are not interchangeable targets, and picking wrong loses real functionality (ticketing vs. per-attendee capacity/booking flow).",
16 "preferBookings": "Small-group, bookable workshops/classes/pop-ups: capped capacity implied by 'limited spots'/'booking required' language, a single or small recurring set of sessions, no ticket tiers, and priced (or free) per-attendee registration rather than a public RSVP/ticket sale.",
17 "preferEvents": "Large public ticketed or open-attendance happenings: galas, concerts, meetups, launches with no attendee cap, or anything the source models with ticket tiers/pricing rather than a single flat per-session price.",
20 "cost_details.values with a single flat value and no ticket 'tiers'/'types' concept -> Bookings-shaped pricing.",
21 "Recurring short sessions of the same class ('2 sessions') -> Bookings COURSE/CLASS, not a Wix Events recurring series.",
22 "The source plugin itself never distinguishes these — the heuristic is read off the CONTENT (title/description/cost shape), not a field the API exposes."
23 ],
24 "confirmWithHuman": "Always ambiguous-case: a human should confirm the classification before the first live write when signals conflict (e.g. a large recurring public series with per-session capacity language). See migrations/reference-run/mapping/entity-decisions/event-plugin-rest.json for one applied precedent (8/8 records classified Bookings on 2026-08-12).",
25 "verifiedPrecedent": "migrations/reference-run, 2026-08-12: all 8 real event-plugin-rest records were workshops/pop-ups with 'Limited spots, booking required' language and flat per-session pricing — classified Bookings Classes, not Wix Events."
79 "summary": "GET /tribe/events/v1/events with no parameters can return total 0 while published events exist; always pass an explicit start_date filter (verified live 2026-08-10 on TEC 6.17.2: parameterless list returned 0, ?start_date=2026-01-01 returned all 3 published events)."
84 "summary": "This entity has TWO real Wix targets (events/event, bookings/service) that are not interchangeable — see the top-level `classificationHeuristic` field for the small-group-workshop-vs-public-happening heuristic and a human-confirmation requirement on ambiguous data. Do not default to events/event without checking it."
85 }
86 ]
87 },
88 {
89 "entity": "venue",
90 "channel": "plugin-rest",
91 "route": "/tribe/events/v1/venues",
92 "recordKeyField": "id",
93 "candidateTargetRefs": [],
94 "pitfalls": [
95 {
96 "code": "folds-into-event-record",
97 "severity": "info",
98 "summary": "Wix has no separate venue entity; this data folds into the event's location/organizer fields. Read it to enrich the event, not as its own collection."
99 }
100 ]
101 },
102 {
103 "entity": "organizer",
104 "channel": "plugin-rest",
105 "route": "/tribe/events/v1/organizers",
106 "recordKeyField": "id",
107 "candidateTargetRefs": [],
108 "pitfalls": [
109 {
110 "code": "folds-into-event-record",
111 "severity": "info",
112 "summary": "Wix has no separate organizer entity; this data folds into the event's location/organizer fields. Read it to enrich the event, not as its own collection."
113 }
114 ]
115 },
116 {
117 "entity": "event-category",
118 "channel": "core-cpt",
119 "route": "/wp/v2/tribe_events_cat",
120 "recordKeyField": "id",
121 "hierarchical": true,
122 "candidateTargetRefs": [
123 "events/category"
124 ],
125 "pitfalls": [
126 {
127 "code": "flat-wix-categories",
128 "severity": "warning",
129 "summary": "Source event categories are hierarchical; Wix Events categories are flat — flatten requires a faithfulness-ledger entry."
130 }
131 ]
132 },
133 {
134 "entity": "event-cpt",
135 "channel": "core-cpt",
136 "route": "/wp/v2/tribe_events",
137 "recordKeyField": "id",
138 "candidateTargetRefs": [
139 "events/event"
140 ],
141 "pitfalls": [
142 {
143 "code": "prefer-tribe-rest-over-cpt",
144 "severity": "info",
145 "summary": "When /tribe/events/v1/events is available prefer it: the CPT route omits venue/organizer/schedule fields the plugin API returns."
146 }
147 ]
148 }
149 ],
150 "excludeRoutes": [
151 {
152 "route": "/tribe/events/v1/doc",
153 "reason": "Swagger self-documentation endpoint, not durable data"
154 }
155 ],
156 "quirks": [
157 "The plugin publishes a Swagger 2.0 document at /wp-json/tribe/events/v1/doc that can be read to confirm the exact endpoint set on a given site.",
158 "Recurring events expand into multiple records; deduplicate by parent event before mapping."