.. spelling:word-list::

   geo
   lat
   lon

.. _rest-subevents:

Event series dates / Sub-events
===============================

Resource description
--------------------

Events can represent whole event series if the ``has_subevents`` property of the event is active.
In this case, many other resources are additionally connected to an event date (also called sub-event).
The sub-event resource contains the following public fields:

.. rst-class:: rest-resource-table

===================================== ========================== =======================================================
Field                                 Type                       Description
===================================== ========================== =======================================================
id                                    integer                    Internal ID of the sub-event
name                                  multi-lingual string       The sub-event's full name
event                                 string                     The slug of the parent event
active                                boolean                    If ``true``, the sub-event ticket shop is publicly
                                                                 available.
is_public                             boolean                    If ``true``, the sub-event ticket shop is publicly
                                                                 shown in lists.
date_from                             datetime                   The sub-event's start date
date_to                               datetime                   The sub-event's end date (or ``null``)
date_admission                        datetime                   The sub-event's admission date (or ``null``)
presale_start                         datetime                   The sub-date at which the ticket shop opens (or ``null``)
presale_end                           datetime                   The sub-date at which the ticket shop closes (or ``null``)
frontpage_text                        multi-lingual string       The description of the event (or ``null``)
location                              multi-lingual string       The sub-event location (or ``null``)
geo_lat                               float                      Latitude of the location (or ``null``)
geo_lon                               float                      Longitude of the location (or ``null``)
item_price_overrides                  list of objects            List of items for which this sub-event overrides the
                                                                 default price or settings
├ item                                integer                    The internal item ID
├ disabled                            boolean                    If ``true``, item should not be available for this sub-event
├ available_from                      datetime                   Start of availability (or ``null``)
├ available_until                     datetime                   End of availability (or ``null``)
└ price                               money (string)             The price or ``null`` for the default price
variation_price_overrides             list of objects            List of variations for which this sub-event overrides
                                                                 the default price or settings
├ variation                           integer                    The internal variation ID
├ disabled                            boolean                    If ``true``, variation should not be available for this sub-event
├ available_from                      datetime                   Start of availability (or ``null``)
├ available_until                     datetime                   End of availability (or ``null``)
└ price                               money (string)             The price or ``null`` for the default price
meta_data                             object                     Values set for organizer-specific meta data parameters.
seating_plan                          integer                    If reserved seating is in use, the ID of a seating
                                                                 plan. Otherwise ``null``.
seat_category_mapping                 object                     An object mapping categories of the seating plan
                                                                 (strings) to items in the event (integers or ``null``).
last_modified                         datetime                   Last modification of this object
===================================== ========================== =======================================================

.. versionchanged:: 4.15

    The ``search`` query parameter has been added to filter sub-events by their name or location in any language.

.. versionchanged:: 5.0

    The ``date_from_before``, ``date_from_after``, ``date_to_before``, and ``date_to_after`` query parameters have been
    added.

.. versionchanged:: 2023.8.0

    For the organizer-wide endpoint, the ``search`` query parameter has been modified to filter sub-events by their parent events slug too.

Endpoints
---------

.. versionchanged:: 4.1

    The ``with_availability_for`` parameter has been added.

.. http:get:: /api/v1/organizers/(organizer)/events/(event)/subevents/

   Returns a list of all sub-events of an event.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/organizers/bigevents/events/sampleconf/subevents/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
          {
            "id": 1,
            "name": {"en": "First Sample Conference"},
            "event": "sampleconf",
            "active": false,
            "is_public": true,
            "date_from": "2017-12-27T10:00:00Z",
            "date_to": null,
            "date_admission": null,
            "presale_start": null,
            "presale_end": null,
            "seating_plan": null,
            "seat_category_mapping": {},
            "location": null,
            "geo_lat": null,
            "geo_lon": null,
            "item_price_overrides": [
              {
                "item": 2,
                "disabled": false,
                "available_from": null,
                "available_until": null,
                "price": "12.00"
              }
            ],
            "variation_price_overrides": [],
            "meta_data": {}
          }
        ]
      }

   :query page: The page number in case of a multi-page result set, default is 1
   :query active: If set to ``true``/``false``, only events with a matching value of ``active`` are returned.
   :query is_future: If set to ``true`` (``false``), only events that happen currently or in the future are (not) returned.
   :query is_past: If set to ``true`` (``false``), only events that are over are (not) returned.
   :query date_from_after: If set to a date and time, only events that start at or after the given time are returned.
   :query date_from_before: If set to a date and time, only events that start at or before the given time are returned.
   :query date_to_after: If set to a date and time, only events that have an end date and end at or after the given time are returned.
   :query date_to_before: If set to a date and time, only events that have an end date and end at or before the given time are returned.
   :query ends_after: If set to a date and time, only events that happen during of after the given time are returned.
   :query search: Only return events matching a given search query.
   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the main event
   :query datetime modified_since: Only return objects that have changed since the given date. Be careful: This does not
       allow you to know if a subevent was deleted.
   :query array attr[meta_data_key]: By providing the key and value of a meta data attribute, the list of sub-events
        will only contain the sub-events matching the set criteria. Providing ``?attr[Format]=Seminar`` would return
        only those sub-events having set their ``Format`` meta data to ``Seminar``, ``?attr[Format]=`` only those, that
        have no value set. Please note that this filter will respect default values set on 
        organizer or event level.
   :query with_availability_for: If set to a sales channel identifier, the response will contain a special ``best_availability_state``
                                 attribute with values of 100 for "tickets available", values less than 100 for "tickets sold out or reserved",
                                 and ``null`` for "status unknown". These values might be served from a cache. This parameter can make the response
                                 slow.
   :statuscode 200: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to view it.

.. http:post:: /api/v1/organizers/(organizer)/events/(event)/subevents/

   Creates a new subevent.

   Permission required: "Can create events"

   **Example request**:

   .. sourcecode:: http

      POST /api/v1/organizers/bigevents/events/sampleconf/subevents/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript
      Content-Type: application/json

      {
        "name": {"en": "First Sample Conference"},
        "active": false,
        "is_public": true,
        "date_from": "2017-12-27T10:00:00Z",
        "date_to": null,
        "date_admission": null,
        "presale_start": null,
        "presale_end": null,
        "location": null,
        "geo_lat": null,
        "geo_lon": null,
        "seating_plan": null,
        "seat_category_mapping": {},
        "item_price_overrides": [
          {
            "item": 2,
            "disabled": false,
            "available_from": null,
            "available_until": null,
            "price": "12.00"
          }
        ],
        "variation_price_overrides": [],
        "meta_data": {}
      }


   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Vary: Accept
      Content-Type: application/json

      {
        "id": 1,
        "name": {"en": "First Sample Conference"},
        "active": false,
        "is_public": true,
        "date_from": "2017-12-27T10:00:00Z",
        "date_to": null,
        "date_admission": null,
        "presale_start": null,
        "presale_end": null,
        "location": null,
        "geo_lat": null,
        "geo_lon": null,
        "seating_plan": null,
        "seat_category_mapping": {},
        "item_price_overrides": [
          {
            "item": 2,
            "disabled": false,
            "available_from": null,
            "available_until": null,
            "price": "12.00"
          }
        ],
        "variation_price_overrides": [],
        "meta_data": {}
      }


   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the main event
   :statuscode 201: no error
   :statuscode 400: The sub-event could not be created due to invalid submitted data.
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.


.. http:get:: /api/v1/organizers/(organizer)/events/(event)/subevents/(id)/

   Returns information on one sub-event, identified by its ID.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/organizers/bigevents/events/sampleconf/subevents/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "id": 1,
        "name": {"en": "First Sample Conference"},
        "event": "sampleconf",
        "active": false,
        "is_public": true,
        "date_from": "2017-12-27T10:00:00Z",
        "date_to": null,
        "date_admission": null,
        "presale_start": null,
        "presale_end": null,
        "location": null,
        "geo_lat": null,
        "geo_lon": null,
        "seating_plan": null,
        "seat_category_mapping": {},
        "item_price_overrides": [
          {
            "item": 2,
            "disabled": false,
            "available_from": null,
            "available_until": null,
            "price": "12.00"
          }
        ],
        "variation_price_overrides": [],
        "meta_data": {}
      }

   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the main event
   :param id: The ``id`` field of the sub-event to fetch
   :statuscode 200: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view it.

.. http:patch:: /api/v1/organizers/(organizer)/events/(event)/subevents/(id)/

   Updates a sub-event, identified by its ID. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to
   provide all fields of the resource, other fields will be reset to default. With ``PATCH``, you only need to provide
   the fields that you want to change.

   Permission required: "Can change event settings"

   **Example request**:

   .. sourcecode:: http

      PATCH /api/v1/organizers/bigevents/events/sampleconf/subevents/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript
      Content-Type: application/json

      {
        "name": {"en": "New Subevent Name"},
        "item_price_overrides": [
          {
            "item": 2,
            "disabled": false,
            "available_from": null,
            "available_until": null,
            "price": "23.42"
          }
        ],
      }

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "id": 1,
        "name": {"en": "New Subevent Name"},
        "event": "sampleconf",
        "active": false,
        "is_public": true,
        "date_from": "2017-12-27T10:00:00Z",
        "date_to": null,
        "date_admission": null,
        "presale_start": null,
        "presale_end": null,
        "location": null,
        "geo_lat": null,
        "geo_lon": null,
        "seating_plan": null,
        "seat_category_mapping": {},
        "item_price_overrides": [
          {
            "item": 2,
            "disabled": false,
            "available_from": null,
            "available_until": null,
            "price": "23.42"
          }
        ],
        "variation_price_overrides": [],
        "meta_data": {}
      }

   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the main event
   :param id: The ``id`` field of the sub-event to update
   :statuscode 200: no error
   :statuscode 400: The sub-event could not be created due to invalid submitted data.
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer/sub-event does not exist **or** you have no permission to update this resource.

.. http:delete:: /api/v1/organizers/(organizer)/events/(event)/subevents/(id)/

   Delete a sub-event. Note that events with orders cannot be deleted to ensure data integrity.

   Permission required: "Can change event settings"

   **Example request**:

   .. sourcecode:: http

      DELETE /api/v1/organizers/bigevents/events/sampleconf/subevents/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Vary: Accept

   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the main event
   :param id: The ``id`` field of the sub-event to delete
   :statuscode 204: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer/sub-event does not exist **or** you have no permission to delete this resource.


.. http:get:: /api/v1/organizers/(organizer)/subevents/

   Returns a list of all sub-events of any event series you have access to within an organizer account.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/organizers/bigevents/subevents/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
          {
            "id": 1,
            "name": {"en": "First Sample Conference"},
            "event": "sampleconf",
            "active": false,
            "is_public": true,
            "date_from": "2017-12-27T10:00:00Z",
            "date_to": null,
            "date_admission": null,
            "presale_start": null,
            "presale_end": null,
            "location": null,
            "geo_lat": null,
            "geo_lon": null,
            "seating_plan": null,
            "seat_category_mapping": {},
            "item_price_overrides": [
              {
                "item": 2,
                "disabled": false,
                "available_from": null,
                "available_until": null,
                "price": "12.00"
              }
            ],
            "variation_price_overrides": [],
            "meta_data": {}
          }
        ]
      }

   :query page: The page number in case of a multi-page result set, default is 1
   :query active: If set to ``true``/``false``, only events with a matching value of ``active`` are returned.
   :query event__live: If set to ``true``/``false``, only events with a matching value of ``live`` on the parent event are returned.
   :query is_future: If set to ``true`` (``false``), only events that happen currently or in the future are (not) returned.
   :query is_past: If set to ``true`` (``false``), only events that are over are (not) returned.
   :query date_from_after: If set to a date and time, only events that start at or after the given time are returned.
   :query date_from_before: If set to a date and time, only events that start at or before the given time are returned.
   :query date_to_after: If set to a date and time, only events that have an end date and end at or after the given time are returned.
   :query date_to_before: If set to a date and time, only events that have an end date and end at or before the given time are returned.
   :query ends_after: If set to a date and time, only events that happen during of after the given time are returned.
   :query search: Only return events matching a given search query.
   :query sales_channel: If set to a sales channel identifier, the response will only contain subevents from events available on this sales channel.
   :param organizer: The ``slug`` field of a valid organizer
   :param event: The ``slug`` field of the event to fetch
   :statuscode 200: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to view it.
