The Events Calendar

New in 3.19.0 (Pro). Two dispatcher tools work with The Events Calendar 6.x (the free edition is enough):

Tool	Default	Purpose
events-calendar-read	On	The setup, events by date and filter, venues, organizers and categories (8 operations)
events-calendar-write	Off	Create and update events, venues, organizers and categories, set an event’s status, trash (12 operations)

Enable the write tool under Tools > Plugins > The Events Calendar. EMCP writes through TEC’s own PHP layer, the one its calendar views use, including the calendar tables its month and list views read. Administrators and editors work on every event; authors on their own; contributors create drafts of their own only.

TEC’s own REST API rebuilds an event from the request on a partial update, deleting its cost, organizers and featured flag and publishing a draft. Use EMCP’s tools instead.

Read first

• get-setup: the version, the time zone mode and site time zone, the enabled views, events per page, date formats, and whether you may create and publish events.
• list-events: by start date with start_after, end_before, status, search, category, venue_id, organizer_id, featured; 20 per page with total.
• get-event: the event’s fields, venue and organizers, categories, tags, event status and its version.
• list-venues / get-venue, list-organizers / get-organizer, list-categories: fields, how many events link to them, and their version.

Build an event

1. create-venue with title and the address (address, city, state_province, zip, country, phone, website, show_map).
2. create-organizer with title, email, phone, website.
3. create-category if needed.
4. create-event with title, start_date, end_date, timezone and the details: content, excerpt, cost, website, currency_symbol, currency_position (prefix or suffix), featured_image, featured, categories, tags, venue_id, organizer_ids. It starts as a draft.
5. get-event to check, then update-event with status: publish.

Dates and time zones

• start_date and end_date are Y-m-d H:i in the event’s own time zone. All-day events take all_day: true with Y-m-d dates.
• timezone is an identifier such as Europe/Paris, UTC, or an offset such as UTC+2. Anything else is invalid_timezone.
• An end before the start is refused (invalid_dates). Changing only the dates keeps the time zone.

Change things

• update-event changes only the fields you pass: venue_id: 0 unlinks the venue, organizer_ids: [] removes the organizers, featured_image: 0 removes the image, cost: "" clears the cost.
• update-venue, update-organizer and update-category work the same way.
• set-event-status with event_status: cancelled or postponed and a reason shown on the event page, or event_status: scheduled to clear it.

Every write to an existing object passes its version. A change made since you read it is a conflict; force: true overwrites on purpose. tec_busy means another change to the same object is running.

Trash, not delete

trash-event, trash-venue and trash-organizer need confirm: true. A venue or organizer that events outside the trash still use is refused (in_use, with the event ids). Categories are never deleted. Recurring events from Events Calendar Pro are read but never written.

On a real site

From our test run with the fictional Larkspur Kitchen School, recorded over a real MCP connection with The Events Calendar’s free edition. The The Events Calendar integration page shows every call the assistant made.

The Events Calendar’s list view, with the featured workshop and the postponed class.

The event page with the venue and organizer the assistant created.

History

Every write can be undone in History: an edit comes back with its dates in TEC’s calendar tables, a new event, venue, organizer or category is removed, and a trashed one gets its earlier status back. An event is never restored onto a venue or organizer that is gone or trashed since (linked_unavailable).