Create or update a calendar post (Event, Venue, Organizer, or Ticket).

For creating: provide postType and data. For updating: provide postType, id, and data.

FREE TICKETS: To create free tickets, omit the price field entirely. WordPress will automatically default to price 0. Do NOT set price to 0 explicitly as this triggers validation errors. Both Tickets Commerce and RSVP providers support free tickets when the price field is omitted.

TICKET AVAILABILITY DATES: Use start_date and end_date fields to control when tickets are available for purchase. start_date is when tickets become available, end_date is when sales stop (typically the event start time). All ticket date fields must be in Y-m-d H:i:s format (e.g., "2024-12-25 15:30:00"). If not provided, defaults to 1 week before event (start) and event start time (end). By default, end_date will be capped to the event start unless you pass allow_end_after_event: true.

SALE PRICING: To offer tickets at a reduced price during specific periods:

• price: Regular ticket price

• sale_price: Discounted price (must be less than regular price)

• sale_price_start_date: When the sale price becomes active

• sale_price_end_date: When the sale price expires (reverts to regular price)

Example: Regular $50 ticket on sale for $35 from Dec 1-15:

{
  "price": 50,
  "sale_price": 35,
  "sale_price_start_date": "2024-12-01",
  "sale_price_end_date": "2024-12-15"
}

NOTE: Ticket availability dates (start_date, end_date) must be provided in Y-m-d H:i:s format. Sale price dates (sale_price_start_date, sale_price_end_date) must be provided in YYYY-MM-DD format. UNLIMITED TICKETS: To create unlimited tickets, set stock_mode to "unlimited".

IMPORTANT: Ensure your event dates and times use the expected formats and timezone context.

Date Formats Supported

• ISO 8601: "2024-12-25T15:00:00"

• Date and time: "2024-12-25 15:00:00"

• Natural language: "tomorrow 2pm", "next monday", "first thursday of next month"

• Relative: "+3 days", "+2 hours", "3 days 1 hour"

• Specific dates: "December 15, 2024 7:00 PM"

Workflow for Events with Dates

1. Calculate appropriate dates for your event

2. Create/update event with calculated dates

Create Examples

Event Creation

The Events Calendar event post type with date, location, and ticketing information

Example 1: Standard event with ISO dates

{
  "postType": "event",
  "data": {
    "title": "Conference Next Week",
    "start_date": "next monday 9am",
    "end_date": "next friday 5pm",
    "all_day": false,
    "timezone": "America/New_York",
    "venues": [
      456
    ],
    "organizers": [
      789
    ]
  }
}

Example 2: Event with natural language dates

{
  "postType": "event",
  "data": {
    "title": "Holiday Party",
    "start_date": "December 15, 2024 7:00 PM",
    "end_date": "December 15, 2024 11:30 PM",
    "all_day": false,
    "timezone": "America/Denver",
    "venues": [
      789
    ],
    "cost": "$25 per person"
  }
}

Example 3: All-day event

{
  "postType": "event",
  "data": {
    "title": "All Day Workshop",
    "start_date": "tomorrow",
    "end_date": "tomorrow",
    "all_day": true,
    "timezone": "Europe/London",
    "cost": "Free"
  }
}

Example 4: Event with venue and organizers

{
  "postType": "event",
  "data": {
    "title": "Summer Music Festival",
    "start_date": "2024-07-15 18:00:00",
    "end_date": "2024-07-15 23:00:00",
    "all_day": false,
    "timezone": "America/Los_Angeles"
  }
}

Venue Creation

Location where events take place, including address and contact information

Example 1: Complete venue with address

{
  "postType": "venue",
  "data": {
    "title": "The Grand Ballroom",
    "venue": "Grand Ballroom at the Historic Hotel",
    "address": "456 Park Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10022",
    "country": "USA",
    "phone": "+1 (212) 555-0123",
    "website": "https://grandballroom.example.com"
  }
}

Example 2: Virtual/online venue

{
  "postType": "venue",
  "data": {
    "title": "Beachside Resort",
    "venue": "Sunset Beach Resort & Spa",
    "address": "1000 Coastal Highway",
    "city": "Miami Beach",
    "state": "FL",
    "zip": "33139",
    "country": "US",
    "phone": "305-555-BEACH",
    "website": "https://sunsetbeachresort.example.com",
    "geo_lat": 25.7906,
    "geo_lng": -80.13
  }
}

Organizer Creation

Person or organization responsible for hosting events

Example 1: Organization with full contact

{
  "postType": "organizer",
  "data": {
    "title": "Local Arts Council",
    "email": "info@localartscouncil.org",
    "website": "https://localartscouncil.org",
    "phone": "(555) 123-4567"
  }
}

Example 2: Individual organizer

{
  "postType": "organizer",
  "data": {
    "title": "DJ Mike Stevens",
    "organizer": "Mike Stevens - Professional DJ",
    "email": "bookings@djmikestevens.com",
    "phone": "+1-555-DJ-MIKE",
    "website": "https://djmikestevens.example.com"
  }
}

Ticket Creation

Event ticket as returned by the API, including read-only fields like sold count and calculated values.

Example 1: Paid general admission

{
  "postType": "ticket",
  "data": {
    "title": "General Admission",
    "event": 123,
    "price": 25,
    "stock": 100,
    "capacity": 100,
    "sku": "GA-2024-001"
  }
}

Example 2: VIP ticket with limited availability

{
  "postType": "ticket",
  "data": {
    "title": "VIP Pass",
    "event": 123,
    "price": 150,
    "stock": 20,
    "capacity": 30,
    "sku": "VIP-2024-001"
  }
}

Update Examples

Updating Events

The Events Calendar event post type with date, location, and ticketing information

Partial update example 1

{
  "postType": "event",
  "id": 124,
  "data": {
    "title": "Conference Next Week",
    "start_date": "next monday 9am",
    "end_date": "next friday 5pm"
  }
}

Partial update example 2

{
  "postType": "event",
  "id": 127,
  "data": {
    "title": "Holiday Party",
    "start_date": "December 15, 2024 7:00 PM",
    "end_date": "December 15, 2024 11:30 PM"
  }
}

Updating Venues

Location where events take place, including address and contact information

Partial update example 1

{
  "postType": "venue",
  "id": 457,
  "data": {
    "address": "456 Park Avenue",
    "city": "New York",
    "phone": "+1 (212) 555-0123"
  }
}

Partial update example 2

{
  "postType": "venue",
  "id": 461,
  "data": {
    "address": "1000 Coastal Highway",
    "city": "Miami Beach",
    "phone": "305-555-BEACH"
  }
}

Read, list, or search calendar posts.

Use Cases

1. Get single post: provide postType and id

2. List all posts: provide postType only

3. Search posts: provide postType and query

Query Capabilities

• Get single post by ID

• List all posts with pagination

• Search posts by keyword

• Filter by post-specific criteria

• Combine multiple filters

Examples

Basic Queries

1. Get specific event by ID

{ "postType": "event", "id": 123 }

2. List all venues with pagination

{ "postType": "venue", "per_page": 20, "page": 1 }

3. Search events by keyword

{ "postType": "event", "search": "conference" }

4. Get all organizers sorted by name

{ "postType": "organizer", "orderby": "title", "order": "asc" }

Date Filtering

5. Get upcoming events

{
  "postType": "event",
  "eventFilters": {
    "start_date": "2024-12-06"
  }
}

6. Get events in date range

{
  "postType": "event",
  "eventFilters": {
    "start_date": "2024-12-01",
    "end_date": "2024-12-31"
  }
}

Location Filtering

7. Find venues by city and state

{
  "postType": "venue",
  "venueFilters": {
    "city": "San Francisco",
    "state": "CA"
  }
}

8. Find venues near coordinates

{
  "postType": "venue",
  "venueFilters": {
    "geo_lat": 37.7749,
    "geo_lng": -122.4194,
    "radius": 10
  }
}

Relationship Queries

9. Get events at specific venue

{ "postType": "event", "eventFilters": { "venue": 456 } }

10. Get tickets for specific event

{ "postType": "ticket", "ticketFilters": { "event": 123 } }

11. Get available tickets only

{
  "postType": "ticket",
  "ticketFilters": {
    "event": 123,
    "available": true
  }
}

Status & Filtering

12. Get only published events

{ "postType": "event", "status": "publish" }

13. Get draft and pending venues

{ "postType": "venue", "status": ["draft", "pending"] }

Complex Queries

14. Search published events at venues with dates

{
  "postType": "event",
  "search": "workshop",
  "status": "publish",
  "eventFilters": {
    "venue": 456,
    "start_date": "2024-12-01"
  },
  "per_page": 50
}

15. Get tickets under $50 sorted by price

{
  "postType": "ticket",
  "ticketFilters": {
    "max_price": 50,
    "available": true
  },
  "orderby": "price",
  "order": "asc"
}

Available Filters

• eventFilters: venue, organizer, featured, categories, tags

• venueFilters: city, state, country, zip, geo_lat/lng, radius

• ticketFilters: event, type, provider, min/max_price

• organizerFilters: email, website, phone

• Common: status, search, include, exclude, page, per_page, orderby

Delete or trash a calendar post (Event, Venue, Organizer, or Ticket).

• Default (force=false or omitted): Moves posts to trash where they can be restored

• Permanent delete (force=true): Permanently deletes posts with no option to restore

Delete Behaviors

• Default (force=false): Moves to trash (recoverable)

• Force delete (force=true): Permanent deletion (not recoverable)

Best Practices

• Always use default trash unless permanent deletion is required

• Consider checking post details before deletion

• For events, verify dates and timezone context first

Examples

Event Deletion

The Events Calendar event post type with date, location, and ticketing information

Move to trash (default, recoverable)

{
  "postType": "event",
  "id": 123
}

Permanent deletion (not recoverable)

{
  "postType": "event",
  "id": 124,
  "force": true
}

Venue Deletion

Location where events take place, including address and contact information

Move to trash (default, recoverable)

{
  "postType": "venue",
  "id": 456
}

Permanent deletion (not recoverable)

{
  "postType": "venue",
  "id": 457,
  "force": true
}

Organizer Deletion

Person or organization responsible for hosting events

Move to trash (default, recoverable)

{
  "postType": "organizer",
  "id": 789
}

Permanent deletion (not recoverable)

{
  "postType": "organizer",
  "id": 790,
  "force": true
}