Reusable media¶
Reusable media represent things, typically physical tokens like plastic cards or NFC wristbands, which can represent other entities inside the system. For example, a medium can link to an order position or to a gift card and can be used in their place. Later, the medium might be reused for a different ticket.
Resource description¶
The reusable medium resource contains the following public fields:
Field |
Type |
Description |
---|---|---|
id |
integer |
Internal ID of the medium |
type |
string |
Type of medium, e.g. |
organizer |
string |
Organizer slug of the organizer who “owns” this medium. |
identifier |
string |
Unique identifier of the medium. The format depends on the |
active |
boolean |
Whether this medium may be used. |
created |
datetime |
Date of creation |
updated |
datetime |
Date of last modification |
expires |
datetime |
Expiry date (or |
customer |
string |
Identifier of a customer account this medium belongs to. |
linked_orderposition |
integer |
Internal ID of a ticket this medium is linked to. |
linked_giftcard |
integer |
Internal ID of a gift card this medium is linked to. |
info |
object |
Additional data, content depends on the |
notes |
string |
Internal notes and comments (or |
Existing media types are:
barcode
nfc_uid
nfc_mf0aes
Endpoints¶
- GET /api/v1/organizers/(organizer)/reusablemedia/¶
Returns a list of all media issued by a given organizer.
Example request:
GET /api/v1/organizers/bigevents/reusablemedia/ 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, "organizer": "bigevents", "identifier": "ABCDEFGH", "created": "2021-04-06T13:44:22.809377Z", "updated": "2021-04-06T13:44:22.809377Z", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": None, "linked_giftcard": None, "notes": None, "info": {} } ] }
- Query Parameters:
page (integer) – The page number in case of a multi-page result set, default is 1.
identifier (string) – Only show media with the given identifier. Note that you should use the lookup endpoint described below for most use cases.
type (string) – Only show media with the given type.
active (boolean) – Only show media that are (not) active.
customer (string) – Only show media linked to the given customer.
created_since (string) – Only show media created since a given date.
updated_since (string) – Only show media updated since a given date.
linked_orderposition (integer) – Only show media linked to the given ticket.
linked_giftcard (integer) – Only show media linked to the given gift card.
expand (string) – If you pass
"linked_giftcard"
,"linked_giftcard.owner_ticket"
,"linked_orderposition"
, or"customer"
, the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that order positions will have an attribute of the format"order": {"code": "ABCDE", "event": "eventslug"}
to make matching easier. The parameter can be given multiple times.
- 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 does not exist or you have no permission to view this resource.
- GET /api/v1/organizers/(organizer)/reusablemedia/(id)/¶
Returns information on one medium, identified by its ID.
Example request:
GET /api/v1/organizers/bigevents/reusablemedia/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, "organizer": "bigevents", "identifier": "ABCDEFGH", "created": "2021-04-06T13:44:22.809377Z", "updated": "2021-04-06T13:44:22.809377Z", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": None, "linked_giftcard": None, "notes": None, "info": {} }
- Parameters:
organizer – The
slug
field of the organizer to fetchid – The
id
field of the medium to fetch
- Query Parameters:
expand (string) – If you pass
"linked_giftcard"
,"linked_giftcard.owner_ticket"
,"linked_orderposition"
, or"customer"
, the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that order positions will have an attribute of the format"order": {"code": "ABCDE", "event": "eventslug"}
to make matching easier. The parameter can be given multiple times.
- Status Codes:
200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to view this resource.
- POST /api/v1/organizers/(organizer)/reusablemedia/lookup/¶
Look up a new reusable medium by its identifier. In some cases, this might lead to the automatic creation of a new medium behind the scenes.
This endpoint, and this endpoint only, might return media from a different organizer if there is a cross-acceptance agreement. In this case, only linked gift cards will be returned, no order position or customer records,
Example request:
POST /api/v1/organizers/bigevents/reusablemedia/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json { "identifier": "ABCDEFGH", "type": "barcode", }
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 1, "organizer": "bigevents", "identifier": "ABCDEFGH", "created": "2021-04-06T13:44:22.809377Z", "updated": "2021-04-06T13:44:22.809377Z", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": None, "linked_giftcard": None, "notes": None, "info": {} }
- Parameters:
organizer – The
slug
field of the organizer to look up a medium for
- Query Parameters:
expand (string) – If you pass
"linked_giftcard"
,"linked_orderposition"
, oder"customer"
, the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that thelinked_orderposition
will have an attribute of the format"order": {"code": "ABCDE", "event": "eventslug"}
to make matching easier. The parameter can be given multiple times.
- Status Codes:
201 Created – no error
400 Bad Request – The medium could not be looked up due to invalid submitted data.
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to create this resource.
- POST /api/v1/organizers/(organizer)/reusablemedia/¶
Creates a new reusable medium.
Example request:
POST /api/v1/organizers/bigevents/reusablemedia/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json { "identifier": "ABCDEFGH", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": None, "linked_giftcard": None, "notes": None, "info": {} }
Example response:
HTTP/1.1 201 Created Vary: Accept Content-Type: application/json { "id": 1, "organizer": "bigevents", "identifier": "ABCDEFGH", "created": "2021-04-06T13:44:22.809377Z", "updated": "2021-04-06T13:44:22.809377Z", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": None, "linked_giftcard": None, "notes": None, "info": {} }
- Parameters:
organizer – The
slug
field of the organizer to create a medium for
- Query Parameters:
expand (string) – If you pass
"linked_giftcard"
,"linked_orderposition"
, oder"customer"
, the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that thelinked_orderposition
will have an attribute of the format"order": {"code": "ABCDE", "event": "eventslug"}
to make matching easier. The parameter can be given multiple times.
- Status Codes:
201 Created – no error
400 Bad Request – The medium could not be created due to invalid submitted data.
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to create this resource.
- PATCH /api/v1/organizers/(organizer)/reusablemedia/(id)/¶
Update a reusable medium. 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
,identifier
andtype
fields.Example request:
PATCH /api/v1/organizers/bigevents/reusablemedia/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json Content-Length: 94 { "linked_orderposition": 13 }
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": 1, "organizer": "bigevents", "identifier": "ABCDEFGH", "created": "2021-04-06T13:44:22.809377Z", "updated": "2021-04-06T13:44:22.809377Z", "type": "barcode", "active": True, "expires": None, "customer": None, "linked_orderposition": 13, "linked_giftcard": None, "notes": None, "info": {} }
- Parameters:
organizer – The
slug
field of the organizer to modifyid – The
id
field of the medium to modify
- Query Parameters:
expand (string) – If you pass
"linked_giftcard"
,"linked_orderposition"
, oder"customer"
, the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that thelinked_orderposition
will have an attribute of the format"order": {"code": "ABCDE", "event": "eventslug"}
to make matching easier. The parameter can be given multiple times.
- Status Codes:
200 OK – no error
400 Bad Request – The medium could not be modified due to invalid submitted data
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to change this resource.