mirror of
https://github.com/pretix/pretix.git
synced 2026-02-03 02:12:27 +00:00
443 lines
15 KiB
ReStructuredText
443 lines
15 KiB
ReStructuredText
Events
|
|
======
|
|
|
|
Resource description
|
|
--------------------
|
|
|
|
The event resource contains the following public fields:
|
|
|
|
.. rst-class:: rest-resource-table
|
|
|
|
===================================== ========================== =======================================================
|
|
Field Type Description
|
|
===================================== ========================== =======================================================
|
|
name multi-lingual string The event's full name
|
|
slug string A short form of the name, used e.g. in URLs.
|
|
live boolean If ``true``, the event ticket shop is publicly
|
|
available.
|
|
testmode boolean If ``true``, the ticket shop is in test mode.
|
|
currency string The currency this event is handled in.
|
|
date_from datetime The event's start date
|
|
date_to datetime The event's end date (or ``null``)
|
|
date_admission datetime The event's admission date (or ``null``)
|
|
is_public boolean If ``true``, the event shows up in places like the
|
|
organizer's public list of events
|
|
presale_start datetime The date at which the ticket shop opens (or ``null``)
|
|
presale_end datetime The date at which the ticket shop closes (or ``null``)
|
|
location multi-lingual string The event location (or ``null``)
|
|
has_subevents boolean ``true`` if the event series feature is active for this
|
|
event. Cannot change after event is created.
|
|
meta_data object Values set for organizer-specific meta data parameters.
|
|
plugins list A list of package names of the enabled plugins for this
|
|
event.
|
|
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``).
|
|
===================================== ========================== =======================================================
|
|
|
|
|
|
.. versionchanged:: 1.7
|
|
|
|
The ``meta_data`` field has been added.
|
|
|
|
.. versionchanged:: 1.15
|
|
|
|
The ``plugins`` field has been added.
|
|
The operations POST, PATCH, PUT and DELETE have been added.
|
|
|
|
.. versionchanged:: 2.1
|
|
|
|
Filters have been added to the list of events.
|
|
|
|
.. versionchanged:: 2.5
|
|
|
|
The ``testmode`` attribute has been added.
|
|
|
|
.. versionchanged:: 2.8
|
|
|
|
When cloning events, the ``testmode`` attribute will now be cloned, too.
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
The attributes ``seating_plan`` and ``seat_category_mapping`` have been added.
|
|
|
|
Endpoints
|
|
---------
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/events/
|
|
|
|
Returns a list of all events within a given organizer the authenticated user/token has access to.
|
|
|
|
Permission required: "Can change event settings"
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/events/ 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": [
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": null,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"has_subevents": false,
|
|
"meta_data": {},
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"plugins": [
|
|
"pretix.plugins.banktransfer"
|
|
"pretix.plugins.stripe"
|
|
"pretix.plugins.paypal"
|
|
"pretix.plugins.ticketoutputpdf"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
|
|
:query page: The page number in case of a multi-page result set, default is 1
|
|
:query is_public: If set to ``true``/``false``, only events with a matching value of ``is_public`` are returned.
|
|
:query live: If set to ``true``/``false``, only events with a matching value of ``live`` are returned.
|
|
:query has_subevents: If set to ``true``/``false``, only events with a matching value of ``has_subevents`` are returned.
|
|
:query is_future: If set to ``true`` (``false``), only events that happen currently or in the future are (not) returned. Event series are never (always) returned.
|
|
:query is_past: If set to ``true`` (``false``), only events that are over are (not) returned. Event series are never (always) returned.
|
|
:query ends_after: If set to a date and time, only events that happen during of after the given time are returned. Event series are never returned.
|
|
:query string ordering: Manually set the ordering of results. Valid fields to be used are ``date_from`` and
|
|
``slug``. Keep in mind that ``date_from`` of event series does not really tell you anything.
|
|
Default: ``slug``.
|
|
:param organizer: The ``slug`` field of a valid organizer
|
|
: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:get:: /api/v1/organizers/(organizer)/events/(event)/
|
|
|
|
Returns information on one event, identified by its slug.
|
|
|
|
Permission required: "Can change event settings"
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/events/sampleconf/ 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
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"has_subevents": false,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.banktransfer"
|
|
"pretix.plugins.stripe"
|
|
"pretix.plugins.paypal"
|
|
"pretix.plugins.ticketoutputpdf"
|
|
]
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to fetch
|
|
:param event: The ``slug`` field of the 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:post:: /api/v1/organizers/(organizer)/events/
|
|
|
|
Creates a new event
|
|
|
|
Please note that events cannot be created as 'live' using this endpoint. Quotas and payment must be added to the
|
|
event before sales can go live.
|
|
|
|
Permission required: "Can create events"
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/events/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"location": null,
|
|
"has_subevents": false,
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal"
|
|
]
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 201 Created
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"has_subevents": false,
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal"
|
|
]
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer of the event to create.
|
|
:statuscode 201: no error
|
|
:statuscode 400: The 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:post:: /api/v1/organizers/(organizer)/events/(event)/clone/
|
|
|
|
Creates a new event with properties as set in the request body. The properties that are copied are: 'is_public',
|
|
`testmode`, settings, plugin settings, items, variations, add-ons, quotas, categories, tax rules, questions.
|
|
|
|
If the 'plugins' and/or 'is_public' fields are present in the post body this will determine their value. Otherwise
|
|
their value will be copied from the existing event.
|
|
|
|
Please note that you can only copy from events under the same organizer.
|
|
|
|
Permission required: "Can create events"
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/events/sampleconf/clone/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"has_subevents": false,
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal"
|
|
]
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 201 Created
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"has_subevents": false,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal"
|
|
]
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer of the event to create.
|
|
:param event: The ``slug`` field of the event to copy settings and items from.
|
|
:statuscode 201: no error
|
|
:statuscode 400: The 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:patch:: /api/v1/organizers/(organizer)/events/(event)/
|
|
|
|
Updates an event
|
|
|
|
Permission required: "Can change event settings"
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
PATCH /api/v1/organizers/bigevents/events/sampleconf/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"plugins": [
|
|
"pretix.plugins.banktransfer",
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal",
|
|
"pretix.plugins.pretixdroid"
|
|
]
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": {"en": "Sample Conference"},
|
|
"slug": "sampleconf",
|
|
"live": false,
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"date_from": "2017-12-27T10:00:00Z",
|
|
"date_to": null,
|
|
"date_admission": null,
|
|
"is_public": false,
|
|
"presale_start": null,
|
|
"presale_end": null,
|
|
"location": null,
|
|
"has_subevents": false,
|
|
"seating_plan": null,
|
|
"seat_category_mapping": {},
|
|
"meta_data": {},
|
|
"plugins": [
|
|
"pretix.plugins.banktransfer",
|
|
"pretix.plugins.stripe",
|
|
"pretix.plugins.paypal",
|
|
"pretix.plugins.pretixdroid"
|
|
]
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer of the event to update
|
|
:param event: The ``slug`` field of the event to update
|
|
:statuscode 200: no error
|
|
:statuscode 400: The event could not be created due to invalid submitted data.
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer/event does not exist **or** you have no permission to create this resource.
|
|
|
|
|
|
.. http:delete:: /api/v1/organizers/(organizer)/events/(event)/items/(id)/
|
|
|
|
Delete an 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/ 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 the organizer to modify
|
|
:param event: The ``slug`` field of the event to delete
|
|
:statuscode 204: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer/event does not exist **or** you have no permission to delete this resource.
|