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. `"barcode"`, `"nfc_uid"` or `"nfc_mf0aes"`.
organizer	string	Organizer slug of the organizer who “owns” this medium.
identifier	string	Unique identifier of the medium. The format depends on the `type`.
active	boolean	Whether this medium may be used.
created	datetime	Date of creation
updated	datetime	Date of last modification
expires	datetime	Expiry date (or `null`)
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 `type`. Consider this internal to the system and don’t use it for your own data.
notes	string	Internal notes and comments (or `null`)

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 fetch
id – 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 the linked_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 the linked_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 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.

You can change all fields of the resource except the id, identifier and type 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 modify
id – 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 the linked_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.