Check-in lists¶
Resource description¶
You can create check-in lists that you can use e.g. at the entrance of your event to track who is coming and if they actually bought a ticket.
You can create multiple check-in lists to separate multiple parts of your event, for example if you have separate entries for multiple ticket types. Different check-in lists are completely independent: If a ticket shows up on two lists, it is valid once on every list. This might be useful if you run a festival with festival passes that allow access to every or multiple performances as well as tickets only valid for single performances.
The check-in list resource contains the following public fields:
Field | Type | Description |
---|---|---|
id | integer | Internal ID of the check-in list |
name | string | The internal name of the check-in list |
all_products | boolean | If true , the check-in lists contains tickets of all products in this event. The limit_products field is ignored in this case. |
limit_products | list of integers | List of item IDs to include in this list. |
subevent | integer | ID of the date inside an event series this list belongs to (or null ). |
position_count | integer | Number of tickets that match this list (read-only). |
checkin_count | integer | Number of check-ins performed on this list (read-only). |
include_pending | boolean | If true , the check-in list also contains tickets from orders in pending state. |
auto_checkin_sales_channels | list of strings | All items on the check-in list will be automatically marked as checked-in when purchased through any of the listed sales channels. |
Changed in version 1.10: This resource has been added.
Changed in version 1.11: The positions
endpoints have been added.
Changed in version 1.13: The include_pending
field has been added.
Changed in version 3.2: The auto_checkin_sales_channels
field has been added.
Endpoints¶
Changed in version 1.15: The ../status/
detail endpoint has been added.
-
GET
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
¶ Returns a list of all check-in lists within a given event.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/checkinlists/ 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": [ { "id": 1, "name": "Default list", "checkin_count": 123, "position_count": 456, "all_products": true, "limit_products": [], "include_pending": false, "subevent": null, "auto_checkin_sales_channels": [ "pretixpos" ] } ] }
Query Parameters: - page (integer) – The page number in case of a multi-page result set, default is 1
- subevent (integer) – Only return check-in lists of the sub-event with the given ID
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)/events/
(event)/checkinlists/
(id)/
¶ Returns information on one check-in list, identified by its ID.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 1, "name": "Default list", "checkin_count": 123, "position_count": 456, "all_products": true, "limit_products": [], "include_pending": false, "subevent": null, "auto_checkin_sales_channels": [ "pretixpos" ] }
Parameters: - organizer – The
slug
field of the organizer to fetch - event – The
slug
field of the event to fetch - id – The
id
field of the check-in list 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.
- organizer – The
-
GET
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
(id)/status/
¶ Returns detailed status information on a check-in list, identified by its ID.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/status/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "checkin_count": 17, "position_count": 42, "event": { "name": "Demo Conference" }, "items": [ { "name": "T-Shirt", "id": 1, "checkin_count": 1, "admission": false, "position_count": 1, "variations": [ { "value": "Red", "id": 1, "checkin_count": 1, "position_count": 12 }, { "value": "Blue", "id": 2, "checkin_count": 4, "position_count": 8 } ] }, { "name": "Ticket", "id": 2, "checkin_count": 15, "admission": true, "position_count": 22, "variations": [] } ] }
Parameters: - organizer – The
slug
field of the organizer to fetch - event – The
slug
field of the event to fetch - id – The
id
field of the check-in list 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.
- organizer – The
-
POST
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
¶ Creates a new check-in list.
Example request:
POST /api/v1/organizers/bigevents/events/sampleconf/checkinlists/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json { "name": "VIP entry", "all_products": false, "limit_products": [1, 2], "subevent": null, "auto_checkin_sales_channels": [ "pretixpos" ] }
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 2, "name": "VIP entry", "checkin_count": 0, "position_count": 0, "all_products": false, "limit_products": [1, 2], "include_pending": false, "subevent": null, "auto_checkin_sales_channels": [ "pretixpos" ] }
Parameters: - organizer – The
slug
field of the organizer of the event/item to create a list for - event – The
slug
field of the event to create a list for
Status Codes: - 201 Created – no error
- 400 Bad Request – The list could not be created due to invalid submitted data.
- 401 Unauthorized – Authentication failure
- 403 Forbidden – The requested organizer/event does not exist or you have no permission to create this resource.
- organizer – The
-
PATCH
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
(id)/
¶ Update a check-in list. You can also use
PUT
instead ofPATCH
. WithPUT
, you have to provide all fields of the resource, other fields will be reset to default. WithPATCH
, you only need to provide the fields that you want to change.You can change all fields of the resource except the
id
field and thecheckin_count
andposition_count
fields.Example request:
PATCH /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json Content-Length: 94 { "name": "Backstage", }
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 2, "name": "Backstage", "checkin_count": 23, "position_count": 42, "all_products": false, "limit_products": [1, 2], "include_pending": false, "subevent": null, "auto_checkin_sales_channels": [ "pretixpos" ] }
Parameters: - organizer – The
slug
field of the organizer to modify - event – The
slug
field of the event to modify - id – The
id
field of the list to modify
Status Codes: - 200 OK – no error
- 400 Bad Request – The list could not be modified due to invalid submitted data
- 401 Unauthorized – Authentication failure
- 403 Forbidden – The requested organizer/event does not exist or you have no permission to change this resource.
- organizer – The
-
DELETE
/api/v1/organizers/
(organizer)/events/
(event)/checkinlist/
(id)/
¶ Delete a check-in list. Note that this also deletes the information on all check-ins performed via this list.
Example request:
DELETE /api/v1/organizers/bigevents/events/sampleconf/checkinlist/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 204 No Content Vary: Accept
Parameters: - organizer – The
slug
field of the organizer to modify - event – The
slug
field of the event to modify - id – The
id
field of the check-in list to delete
Status Codes: - 204 No Content – no error
- 401 Unauthorized – Authentication failure
- 403 Forbidden – The requested organizer/event does not exist or you have no permission to delete this resource.
- organizer – The
Order position endpoints¶
Changed in version 1.15: The order positions endpoint has been extended by the filter queries item__in
, variation__in
,
order__status__in
, subevent__in
, addon_to__in
, and search
. The search for attendee names and order
codes is now case-insensitive.
The .../redeem/
endpoint has been added.
Changed in version 2.0: The order positions endpoint has been extended by the filter queries voucher
and voucher__code
.
Changed in version 2.7: The resource now contains the new attributes require_attention
and order__status
and accepts the new
ignore_status
filter. The attendee_name
field is now “smart” (see below) and the redemption endpoint
returns 400
instead of 404
on tickets which are known but not paid.
Changed in version 3.2: The checkins
dict now also contains a auto_checked_in
value to indicate if the check-in has been performed
automatically by the system.
-
GET
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
(list)/positions/
¶ Returns a list of all order positions within a given event. The result is the same as the Order position resource, with the following differences:
- The
checkins
value will only include check-ins for the selected list. - An additional boolean property
require_attention
will inform you whether either the order or the item have thecheckin_attention
flag set. - If
attendee_name
is empty, it will automatically fall back to values from a parent product or from invoice addresses.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/positions/ 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": [ { "id": 23442, "order": "ABC12", "positionid": 1, "item": 1345, "variation": null, "price": "23.00", "attendee_name": "Peter", "attendee_name_parts": { "full_name": "Peter", }, "attendee_email": null, "voucher": null, "tax_rate": "0.00", "tax_rule": null, "tax_value": "0.00", "secret": "z3fsn8jyufm5kpk768q69gkbyr5f4h6w", "addon_to": null, "subevent": null, "pseudonymization_id": "MQLJvANO3B", "seat": null, "checkins": [ { "list": 1, "datetime": "2017-12-25T12:45:23Z", "auto_checked_in": true } ], "answers": [ { "question": 12, "answer": "Foo", "options": [] } ], "downloads": [ { "output": "pdf", "url": "https://pretix.eu/api/v1/organizers/bigevents/events/sampleconf/orderpositions/23442/download/pdf/" } ] } ] }
Query Parameters: - page (integer) – The page number in case of a multi-page result set, default is 1
- ignore_status (string) – If set to
true
, results will be returned regardless of the state of the order they belong to and you will need to do your own filtering by order status. - ordering (string) – Manually set the ordering of results. Valid fields to be used are
order__code
,order__datetime
,positionid
,attendee_name
,last_checked_in
andorder__email
. Default:attendee_name,positionid
- order (string) – Only return positions of the order with the given order code
- search (string) – Fuzzy search matching the attendee name, order code, invoice address name as well as to the beginning of the secret.
- item (integer) – Only return positions with the purchased item matching the given ID.
- item__in (integer) – Only return positions with the purchased item matching one of the given comma-separated IDs.
- variation (integer) – Only return positions with the purchased item variation matching the given ID.
- variation__in (integer) – Only return positions with one of the purchased item variation matching the given comma-separated IDs.
- attendee_name (string) – Only return positions with the given value in the attendee_name field. Also, add-on products positions are shown if they refer to an attendee with the given name.
- secret (string) – Only return positions with the given ticket secret.
- order__status (string) – Only return positions with the given order status.
- order__status__in (string) – Only return positions with one the given comma-separated order status.
- has_checkin (boolean) – If set to
true
orfalse
, only return positions that have or have not been checked in already. - subevent (integer) – Only return positions of the sub-event with the given ID
- subevent__in (integer) – Only return positions of one of the sub-events with the given comma-separated IDs
- addon_to (integer) – Only return positions that are add-ons to the position with the given ID.
- addon_to__in (integer) – Only return positions that are add-ons to one of the positions with the given comma-separated IDs.
- voucher (string) – Only return positions with a specific voucher.
- voucher__code (string) – Only return positions with a specific voucher code.
Parameters: - organizer – The
slug
field of the organizer to fetch - event – The
slug
field of the event to fetch - list – The ID of the check-in list to look for
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.
- 404 Not Found – The requested check-in list does not exist.
- The
-
GET
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
(list)/positions/
(id)/
¶ Returns information on one order position, identified by its internal ID. The result is the same as the Order position resource, with the following differences:
- The
checkins
value will only include check-ins for the selected list. - An additional boolean property
require_attention
will inform you whether either the order or the item have thecheckin_attention
flag set. - If
attendee_name
is empty, it will automatically fall back to values from a parent product or from invoice addresses.
Instead of an ID, you can also use the ``secret`` field as the lookup parameter.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/positions/23442/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 23442, "order": "ABC12", "positionid": 1, "item": 1345, "variation": null, "price": "23.00", "attendee_name": "Peter", "attendee_name_parts": { "full_name": "Peter", }, "attendee_email": null, "voucher": null, "tax_rate": "0.00", "tax_rule": null, "tax_value": "0.00", "secret": "z3fsn8jyufm5kpk768q69gkbyr5f4h6w", "addon_to": null, "subevent": null, "pseudonymization_id": "MQLJvANO3B", "seat": null, "checkins": [ { "list": 1, "datetime": "2017-12-25T12:45:23Z", "auto_checked_in": true } ], "answers": [ { "question": 12, "answer": "Foo", "options": [] } ], "downloads": [ { "output": "pdf", "url": "https://pretix.eu/api/v1/organizers/bigevents/events/sampleconf/orderpositions/23442/download/pdf/" } ] }
Parameters: - organizer – The
slug
field of the organizer to fetch - event – The
slug
field of the event to fetch - list – The ID of the check-in list to look for
- id – The
id
field of the order position 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.
- 404 Not Found – The requested order position or check-in list does not exist.
- The
-
POST
/api/v1/organizers/
(organizer)/events/
(event)/checkinlists/
(list)/positions/
(id)/redeem/
¶ Tries to redeem an order position, identified by its internal ID, i.e. checks the attendee in. This endpoint accepts a number of optional requests in the body.
Instead of an ID, you can also use the ``secret`` field as the lookup parameter.
Request JSON Object: - questions_supported (boolean) – When this parameter is set to
true
, handling of questions is supported. If you do not implement question handling in your user interface, you must set this tofalse
. In that case, questions will just be ignored. Defaults totrue
. - canceled_supported (boolean) – When this parameter is set to
true
, the response codecanceled
may be returned. Otherwise, canceled orders will returnunpaid
. - datetime (datetime) – Specifies the datetime of the check-in. If not supplied, the current time will be used.
- force (boolean) – Specifies that the check-in should succeed regardless of previous check-ins or required
questions that have not been filled. Defaults to
false
. - ignore_unpaid (boolean) – Specifies that the check-in should succeed even if the order is in pending state.
Defaults to
false
and only works wheninclude_pending
is set on the check-in list. - nonce (string) – You can set this parameter to a unique random value to identify this check-in. If you’re sending this request twice with the same nonce, the second request will also succeed but will always create only one check-in object even when the previous request was successful as well. This allows for a certain level of idempotency and enables you to re-try after a connection failure.
- answers (object) – If questions are supported/required, you may/must supply a mapping of question IDs to their respective answers. The answers should always be strings. In case of (multiple-)choice-type answers, the string should contain the (comma-separated) IDs of the selected options.
Example request:
POST /api/v1/organizers/bigevents/events/sampleconf/checkinlists/1/positions/234/redeem/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript { "force": false, "ignore_unpaid": false, "nonce": "Pvrk50vUzQd0DhdpNRL4I4OcXsvg70uA", "datetime": null, "questions_supported": true, "canceled_supported": true, "answers": { "4": "XS" } }
Example successful response:
HTTP/1.1 201 Created Vary: Accept Content-Type: application/json { "status": "ok", "position": { … } }
Example response with required questions:
HTTP/1.1 400 Bad Request Content-Type: text/json { "status": "incomplete", "position": { … }, "questions": [ { "id": 1, "question": {"en": "T-Shirt size"}, "type": "C", "required": false, "items": [1, 2], "position": 1, "identifier": "WY3TP9SL", "ask_during_checkin": true, "options": [ { "id": 1, "identifier": "LVETRWVU", "position": 0, "answer": {"en": "S"} }, { "id": 2, "identifier": "DFEMJWMJ", "position": 1, "answer": {"en": "M"} }, { "id": 3, "identifier": "W9AH7RDE", "position": 2, "answer": {"en": "L"} } ] } ] }
Example error response:
HTTP/1.1 200 OK Content-Type: text/json { "status": "error", "reason": "unpaid", "position": { … } }
Possible error reasons:
unpaid
- Ticket is not paid forcanceled
– Ticket is canceled or expired. This reason is only sent when your request setscanceled_supported
totrue
, otherwise these orders returnunpaid
.already_redeemed
- Ticket already has been redeemedproduct
- Tickets with this product may not be scanned at this device
Parameters: - organizer – The
slug
field of the organizer to fetch - event – The
slug
field of the event to fetch - list – The ID of the check-in list to look for
- id – The
id
field of the order position to fetch
Status Codes: - 201 Created – no error
- 400 Bad Request – Invalid or incomplete request, see above
- 401 Unauthorized – Authentication failure
- 403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.
- 404 Not Found – The requested order position or check-in list does not exist.
- questions_supported (boolean) – When this parameter is set to