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:
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:
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:
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:
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.