---
description: "Find accessible event IDs and retrieve the v2 event resource."
group: "Resources"
order: 11
---

# Working with events

Find accessible event IDs and retrieve the v2 event resource.

Events are the starting point for event scoped products, orders, and attendees. Use the event UUID in API paths and the event slug when linking visitors to the public ticket shop.

## Discover events {#discover-events}

`GET /events/my.json` returns an `events` array with an `Event` object in each record. It also reports `loaded_years` and `oldest_available_year`. Without a year, the list covers the current and previous year; pass a four digit `year` to request another year.

```curl
curl --user "$PAYDRO_EMAIL:$PAYDRO_PASSWORD" \
  --header 'Accept: application/json' \
  "$PAYDRO_ORIGIN/events/my.json?year=2026"
```

The discovery list requires company membership and excludes events whose names contain “test”. Without a year filter, the result is capped at 2,000 events; an explicit year removes that cap. A test event can therefore be accessible by its UUID without appearing in discovery. Keep its ID from the organizer URL.

## Retrieve an event {#retrieve-an-event}

```curl
curl --user "$PAYDRO_EMAIL:$PAYDRO_PASSWORD" \
  --header 'Accept: application/json' \
  "$PAYDRO_ORIGIN/api/v2/events/$EVENT_ID"
```

The response has an `Event` object containing fields such as `id`, `name`, `start_date`, `end_date`, `currency`, `timezone`, and shop links. It also includes legacy settings and metadata; use only the fields your integration needs.

## Use public shop links {#use-public-shop-links}

The `direct_link` field identifies the visitor facing shop. Do not expose organizer credentials in that link. Check the event’s published state before directing visitors to it.

## Keep event data current {#keep-event-data-current}

Refresh event details when displaying dates or links. Treat timezone changes and moved dates as actual changes, and synchronize related records by their stable IDs.

## Create and edit events {#create-and-edit-events}

POST `/events/add.json` with an `Event` object to create an event on the authorized company hostname. The server assigns company/defaults and filters protected fields. Supply event name, dates, currency and timezone. Success returns `{"ok":true,"event_id":"..."}`; validation errors can retain legacy HTTP 200 handling.

```curl
{"Event":{"name":"Example conference","start_date":"2026-11-20 09:00:00","end_date":"2026-11-20 18:00:00","currency":"EUR","timezone":"Europe/Amsterdam"}}
```

PUT `/{event_id}/events/edit.json` updates allowed `Event` fields and metadata transactionally. Send both dates when changing dates; protected date/sales rules apply. POST `/events/duplicate/{event_id}.json` duplicates authorized configuration and selected related records; waiting-list invitation codes are excluded. Duplicate success returns `id`, rather than `event_id`.

## Change shop status {#change-shop-status}

PUT `/{event_id}/events/status/{status}.json` with status `open`, `close` or `sold_out`. Opening can require company clearance. A transition from a concept/test event cleans concept test state transactionally. Success returns `status:200` and updated `Event` context. Aliases `events/open_shop.json`, `close_shop.json` and `sell_out_shop.json` use the same PUT implementation.

`GET /{event_id}/dashboard/shop_status.json` returns organizer-facing status messages, rather than an inventory count. Use [product availability](/en-us/docs/product-availability.md) for capacity and sales-rule interpretation.

Use the [complete event/catalog recipe](/en-us/docs/integration-recipes.md#create-event-catalog) to create categories, questions and ticket products after creating the event.

## Event write fields {#event-write-fields}

| Field | Meaning and rules |
| --- | --- |
| `Event.name` | Non-empty name. Creation starts with a server/company default such as Untitled event; supply your intended name. |
| `Event.start_date`, `Event.end_date` | Server-local SQL timestamps. Creation merges server defaults; send deliberate future dates. Send both when changing a schedule. Existing sales and date-protection rules can retain protected dates. |
| `Event.currency` | Event currency, such as EUR. Company configuration supplies creation defaults; retain the established currency when editing. |
| `Event.timezone` | IANA timezone, such as Europe/Amsterdam. SQL timestamps do not carry an offset; interpret them with the event's configuration. |
| `Event.email_name`, `Event.email_mail` | Organizer email sender name/address; company defaults and field validation apply. |
| `Event.Meta`, `Meta` | Server-allowlisted metadata. Protected company/provider/security settings are not arbitrary writable keys. Read settings back to confirm permitted changes. |
| `Event.company_id`, `Event.id` | Server/route-owned. A creation company mismatch is rejected; use the correct company hostname. |

Mutations require company manager/editor or administrator rights. An event edit filters protected fields and is not a guarantee that every submitted setting changed. Follow the returned `event_id` or `id`, then retrieve the event and compare the relevant fields. Shop publication is a separate status operation.

## Full organizer configuration {#full-organizer-configuration}

`GET /{event_id}/events/get_event_data.json` returns a broader internal configuration projection with metadata and sensitive settings. Keep it on your server and retain only the fields needed by your integration. Prefer the cleaned v2 event resource for ordinary reads. Review [writing data](/en-us/docs/writing-data.md) before enabling configuration or status changes.