Data exporters

pretix and it’s plugins include a number of data exporters that allow you to bulk download various data from pretix in different formats. This page shows you how to use these exporters through the API.

Warning

While we consider the methods listed on this page to be a stable API, the availability and specific input field requirements of individual exporters is not considered a stable API. Specific exporters and their input parameters may change at any time without warning.

Listing available exporters

GET /api/v1/organizers/(organizer)/events/(event)/exporters/

Returns a list of all exporters available for a given event. You will receive a list of export methods as well as their supported input fields. Note that the exact type and validation requirements of the input fields are not given in the response, and you might need to look into the pretix web interface to figure out the exact input required.

Example request:

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

Example response:

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "identifier": "orderlist",
      "verbose_name": "Order data",
      "input_parameters": [
        {
          "name": "_format",
          "required": true,
          "choices": [
            "xlsx",
            "orders:default",
            "orders:excel",
            "orders:semicolon",
            "positions:default",
            "positions:excel",
            "positions:semicolon",
            "fees:default",
            "fees:excel",
            "fees:semicolon"
          ]
        },
        {
          "name": "paid_only",
          "required": false
        }
      ]
    }
  ]
}
Query Parameters:

  • page (integer) – The page number in case of a multi-page result set, default is 1

Parameters:

  • organizer – The slug field of the organizer to fetch

  • event – The slug field of the event to fetch

Status Codes:

  • 200 OK – no error

  • 401 Unauthorized – Authentication failure

  • 403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.

GET /api/v1/organizers/(organizer)/exporters/

Returns a list of all cross-event exporters available for a given organizer. You will receive a list of export methods as well as their supported input fields. Note that the exact type and validation requirements of the input fields are not given in the response, and you might need to look into the pretix web interface to figure out the exact input required.

Example request:

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

Example response:

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "identifier": "orderlist",
      "verbose_name": "Order data",
      "input_parameters": [
        {
          "name": "events",
          "required": false
        },
        {
          "name": "_format",
          "required": true,
          "choices": [
            "xlsx",
            "orders:default",
            "orders:excel",
            "orders:semicolon",
            "positions:default",
            "positions:excel",
            "positions:semicolon",
            "fees:default",
            "fees:excel",
            "fees:semicolon"
          ]
        },
        {
          "name": "paid_only",
          "required": false
        }
      ]
    }
  ]
}
Query Parameters:

  • page (integer) – The page number in case of a multi-page result set, default is 1

Parameters:

  • organizer – The slug field of the organizer to fetch

Status Codes:

  • 200 OK – no error

  • 401 Unauthorized – Authentication failure

  • 403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.

Running an export

Since exports often include large data sets, they might take longer than the duration of an HTTP request. Therefore, creating an export is a two-step process. First you need to start an export task with one of the following to API endpoints:

POST /api/v1/organizers/(organizer)/events/(event)/exporters/(identifier)/run/

Starts an export task. If your input parameters validate correctly, a 202 Accepted status code is returned. The body points you to the download URL of the result.

Example request:

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

{
  "_format": "xlsx"
}

Example response:

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

{
  "download": "https://pretix.eu/api/v1/organizers/bigevents/events/sampleconf/exporters/orderlist/download/29891ede-196f-4942-9e26-d055a36e98b8/3f279f13-c198-4137-b49b-9b360ce9fcce/"
}
Parameters:

  • organizer – The slug field of the organizer to fetch

  • event – The slug field of the event to fetch

  • identifier – The identifier field of the exporter to run

Status Codes:
POST /api/v1/organizers/(organizer)/exporters/(identifier)/run/

The endpoint for organizer-level exports works just like event-level exports (see above).

Downloading the result

When starting an export, you receive a url for downloading the result. Running a GET request on that result will yield one of the following status codes:

  • 200 OK – The export succeeded. The body will be your resulting file. Might be large!

  • 409 Conflict – Your export is still running. The body will be JSON with the structure {"status": "running", "percentage": 40}. percentage can be null if it is not known and status can be waiting before the task is actually being processed. Please retry, but wait at least one second before you do.

  • 410 Gone – Running the export has failed permanently. The body will be JSON with the structure {"status": "failed", "message": "Error message"}

  • 404 Not Found – The export does not exist / is expired.

Warning

Running exports puts a lot of stress on the system, we kindly ask you not to run more than two exports at the same time.