The Events Calendar ability reference

How an event time travels from the request into The Events Calendar

The abilities accept start and end as Y-m-d H:i:s, but The Events Calendar's own API does not read that format. It parses the date half with the site's datepicker format setting (n/j/Y out of the box) and only replaces the stored schedule when it is given a date and a time for both ends. GoBuildWP therefore splits each value into EventStartDate or EventEndDate, written in the site's datepicker format, plus EventStartTime or EventEndTime in 24-hour form. The source records why: the raw format was once stamped with the time of the request on a new event and ignored on an edit, while both calls reported success.

Validation is strict. A value PHP would quietly roll over, such as 31 April, is rejected with events_calendar_invalid_date instead of becoming 1 May. An edit that sends neither start nor end leaves the schedule untouched. The listing's start_date and end_date filters are plain Y-m-d dates checked before the query runs. Reads return the stored times as ISO 8601 with an offset, so after any schedule change compare those strings, offset included, with what was intended rather than trusting the success flag.

Event fields GoBuildWP can set, and the ones it cannot clear

Only the fields sent are mapped into The Events Calendar's update, so a partial edit does not blank the rest. The limits and conversions below come from the module's input schema and its mapping code.

• title (1 to 500 characters), excerpt (up to 10,000) and status are sanitised as plain text; content (up to 200,000) passes through wp_kses_post, so scripts and disallowed markup are stripped.
• status on a write is draft, publish, pending or private; the listing can additionally filter by future.
• website goes through esc_url_raw, and cost is stored as text of up to 100 characters.
• venue_id and organizer_id attach one venue and one organiser when they are positive. Neither accepts zero, so an existing venue or organiser cannot be removed through GoBuildWP; do that in the event editor.
• category_ids (up to 100) is sent as the event's tribe_events_cat list, so include every category the event should keep.
• There is no recurrence input. Recurring series from Events Calendar Pro are not exposed, and an edit should never be described as applying to a whole series.
• An edit needs event_id plus at least one other field; when nothing usable is left after mapping it returns events_calendar_no_changes.

Undo for events: creates roll back, edits and deletes do not

The change ledger treats the event writes differently. A create is recorded against the tribe_events post type, so wppilot/rollback-change can remove the event it made; the ledger map notes that the event is trashed through The Events Calendar's own hooks. Edits and deletes are recorded as irreversible, because The Events Calendar 6 mirrors dates into its tec_events and tec_occurrences tables and a plain post restore is not guaranteed to resync them (see change ledger and rollback).

The practical undo for an edit is a before-image: the full wppilot/events-calendar-get-event result taken before the change, whose fields can be sent back through wppilot/events-calendar-edit-event, except that a venue or organiser added by the edit cannot be detached that way. A delete without force uses WordPress's own trash on purpose, because tribe_delete_event() would have removed the event outright; a forced delete has no way back through GoBuildWP.

Event Tickets: active is not the same as available

wppilot/events-calendar-check-setup reports tickets.plugin_active and tickets.available separately. The first only says Event Tickets is loaded; the second also requires version 5.8.0 or newer and its Tribe__Tickets__Tickets class. Only available: true means wppilot/events-calendar-list-event-tickets will answer; otherwise it returns events_calendar_tickets_unavailable even with the plugin switched on, and the fix is an Event Tickets update.

Each ticket row gives the id, name, description, price as text, capacity and stock (null when Event Tickets holds no value), the sale start and end exactly as stored, and the provider class name. The ticket call checks the event first, so a trashed or wrong-type id is refused with events_calendar_event_not_found before Event Tickets is asked anything.

Permissions, profiles and event error codes

Every event call relies on GoBuildWP's own permission check alone. The edit_tribe_events, publish_tribe_events and delete_tribe_events values in check-setup are reported for information; the abilities do not test them. Under the Read Only safety profile the reads remain and every write disappears. Under Production Safe a create runs without confirmation and lands as a draft unless status says otherwise, while edits and deletes need confirm: true or a person's approval. The edit's own instructions single out publishing and date changes as the edits to put to the user explicitly.

• events_calendar_event_not_found: the id is not a tribe_events post, or it is trashed or an auto-draft; list again with the right status.
• events_calendar_create_failed or events_calendar_update_failed: tribe_create_event() or tribe_update_event() returned no id; read the event before retrying so a change is not applied twice.
• events_calendar_delete_failed: the trash or permanent delete did not happen; check the Events list in wp-admin.
• events_calendar_query_failed: tribe_get_events() did not return a query object, which points at The Events Calendar itself rather than at the input.

Worked request: publishing a workshop at a named venue

Request: add the pottery workshop on 18 October from 10:00 to 13:00 at the Market Hall and publish it. The agent runs wppilot/events-calendar-check-setup, then needs the venue id; the module has no venue lookup, so the id comes from the user, from wp-admin, or from wppilot/events-calendar-get-event on an earlier event at that venue. It creates a draft with wppilot/events-calendar-create-event, shows the stored event, and publishes with wppilot/events-calendar-edit-event, status publish and confirm: true.

On staging, check that the returned start and end carry the intended date, time and offset, that venue_id matches, that the event page shows the right venue, and that the event appears on the calendar for that day. If the whole request was a mistake, wppilot/rollback-change on the create removes the event, but the publishing edit itself is recorded as irreversible.