Events API

REST API endpoints for creating, listing, updating events and reading attendees.

An event is a product flagged as an event (with a date, location, and capacity) and a single non-shippable ticket variant. Tickets are sold through the normal cart and checkout, and ticketsSold/attendees are derived from paid orders.

All endpoints require the Events tool to be enabled for the store — requests return 404 when it is off. Because events are products, they are excluded from GET /api/v1/products by default; pass ?includeEvents=true there to include them, or use the endpoints below.

List Events

GET /api/v1/events

Returns the store's events with their event metadata and tickets-sold counts (derived from paid orders).

Query Parameters

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Summer Fest",
      "slug": "summer-fest",
      "images": ["https://cdn.store.com/fest.jpg"],
      "event": {
        "enabled": true,
        "startsAt": "2026-07-01T18:00:00.000Z",
        "location": "Berlin",
        "capacity": 500
      },
      "ticketsSold": 142
    }
  ],
  "total": 1
}

Get Event

GET /api/v1/events/:idOrSlug

Returns a single event by product UUID or URL slug. Returns 404 when the product is not an enabled event.

Response

{
  "event": {
    "id": "0191abc0-1234-7def-8000-000000000001",
    "name": "Summer Fest",
    "slug": "summer-fest",
    "summary": "An open-air music festival",
    "status": "published",
    "images": ["https://cdn.store.com/fest.jpg"],
    "event": {
      "enabled": true,
      "startsAt": "2026-07-01T18:00:00.000Z",
      "location": "Berlin",
      "capacity": 500
    }
  }
}

Create Event

POST /api/v1/events

Creates an event — internally a product with a single non-shippable ticket variant priced at price. Image URLs are downloaded and re-uploaded to the store's CDN. The slug is generated from name when omitted and must be unique within the store.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Fest",
    "price": "29.99",
    "startsAt": "2026-07-01T18:00:00Z",
    "location": "Berlin",
    "capacity": 500,
    "images": ["https://example.com/fest.jpg"]
  }' \
  https://your-store.yns.store/api/v1/events

Response (201)

{
  "message": "Event created successfully",
  "event": {
    "id": "0191abc0-1234-7def-8000-000000000001",
    "slug": "summer-fest",
    "name": "Summer Fest",
    "status": "published",
    "startsAt": "2026-07-01T18:00:00Z",
    "location": "Berlin",
    "capacity": 500,
    "images": ["https://cdn.store.com/fest-abc123.jpg"]
  }
}

Returns 409 when the slug already exists in the store.

Update Event

PATCH /api/v1/events/:idOrSlug

Partially updates event metadata. Only the fields you send are changed — omit a field to leave it unchanged, or send null to clear it. This endpoint does not change the ticket price or variants (use the Products API for those).

Request Body

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"capacity": 600, "status": "published"}' \
  https://your-store.yns.store/api/v1/events/summer-fest

Response

{
  "message": "Event updated successfully",
  "event": { "id": "0191abc0-1234-7def-8000-000000000001" }
}

Returns 404 when the event does not exist.

Event Attendees

GET /api/v1/events/:idOrSlug/attendees

Returns the attendee rollup for an event: buyers (name and email) with summed ticket quantities, aggregated from paid orders whose line items reference the event. Returns 404 when the product is not an enabled event.

Response

{
  "attendees": [
    { "name": "Jane Doe", "email": "jane@example.com", "quantity": 2 },
    { "name": "John Smith", "email": "john@example.com", "quantity": 1 }
  ],
  "totalTickets": 3
}