Data model

pretix provides the following data(base) models. Every model and every model method or field that is not documented here is considered private and should not be used by third-party plugins, as it may change without advance notice.

User model

class pretix.base.models.User(*args, **kwargs)

This is the user model used by pretix for authentication.

Parameters
  • email (str) – The user’s email address, used for identification.

  • fullname (str) – The user’s full name. May be empty or null.

  • is_active (bool) – Whether this user account is activated.

  • is_staff (bool) – True for system operators.

  • date_joined (datetime) – The datetime of the user’s registration.

  • locale (str) – The user’s preferred locale code.

  • needs_password_change (bool) – Whether this user’s password needs to be changed.

  • timezone (str) – The user’s preferred timezone.

  • auth_backend (str) – The identifier of the authentication backend plugin responsible for managing this user.

  • auth_backend_identifier (str) – The native identifier of the user provided by a non-native authentication backend.

exception DoesNotExist
exception MultipleObjectsReturned
get_event_permission_set(organizer, event) → set

Gets a set of permissions (as strings) that a user holds for a particular event

Parameters
  • organizer – The organizer of the event

  • event – The event to check

Returns

set

get_events_with_any_permission(request=None)

Returns a queryset of events the user has any permissions to.

Parameters

request – The current request (optional). Required to detect staff sessions properly.

Returns

Iterable of Events

get_events_with_permission(permission, request=None)

Returns a queryset of events the user has a specific permissions to.

Parameters

request – The current request (optional). Required to detect staff sessions properly.

Returns

Iterable of Events

get_full_name() → str

Returns the first of the following user properties that is found to exist:

  • Full name

  • Email address

get_organizer_permission_set(organizer) → set

Gets a set of permissions (as strings) that a user holds for a particular organizer

Parameters

organizer – The organizer of the event

Returns

set

get_organizers_with_any_permission(request=None)

Returns a queryset of organizers the user has any permissions to.

Parameters

request – The current request (optional). Required to detect staff sessions properly.

Returns

Iterable of Organizers

get_organizers_with_permission(permission, request=None)

Returns a queryset of organizers the user has a specific permissions to.

Parameters

request – The current request (optional). Required to detect staff sessions properly.

Returns

Iterable of Organizers

get_session_auth_hash()

Return an HMAC that needs to

get_short_name() → str

Returns the first of the following user properties that is found to exist:

  • Full name

  • Email address

Only present for backwards compatibility

has_active_staff_session(session_key=None)

Returns whether or not a user has an active staff session (formerly known as superuser session) with the given session key.

has_event_permission(organizer, event, perm_name=None, request=None) → bool

Checks if this user is part of any team that grants access of type perm_name to the event event.

Parameters
  • organizer – The organizer of the event

  • event – The event to check

  • perm_name – The permission, e.g. can_change_teams

  • request – The current request (optional). Required to detect staff sessions properly.

Returns

bool

has_organizer_permission(organizer, perm_name=None, request=None)

Checks if this user is part of any team that grants access of type perm_name to the organizer organizer.

Parameters
  • organizer – The organizer to check

  • perm_name – The permission, e.g. can_change_teams

  • request – The current request (optional). Required to detect staff sessions properly.

Returns

bool

property is_superuser

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

Organizers and events

class pretix.base.models.Organizer(*args, **kwargs)

This model represents an entity organizing events, e.g. a company, institution, charity, person, …

Parameters
  • name (str) – The organizer’s name

  • slug (str) – A globally unique, short name for this organizer, to be used in URLs and similar places.

exception DoesNotExist
exception MultipleObjectsReturned
cache

Returns an ObjectRelatedCache object. This behaves equivalent to Django’s built-in cache backends, but puts you into an isolated environment for this organizer, so you don’t have to prefix your cache keys. In addition, the cache is being cleared every time the organizer changes.

get_cache()

Returns an ObjectRelatedCache object. This behaves equivalent to Django’s built-in cache backends, but puts you into an isolated environment for this organizer, so you don’t have to prefix your cache keys. In addition, the cache is being cleared every time the organizer changes.

Deprecated since version 1.9: Use the property cache instead.

get_mail_backend(timeout=None)

Returns an email server connection, either by using the system-wide connection or by returning a custom one based on the organizer’s settings.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

set_defaults()

This will be called after organizer creation. This way, we can use this to introduce new default settings to pretix that do not affect existing organizers.

class pretix.base.models.Event(*args, **kwargs)

This model represents an event. An event is anything you can buy tickets for.

Parameters
  • organizer (Organizer) – The organizer this event belongs to

  • testmode (bool) – This event is in test mode

  • name (str) – This event’s full title

  • slug (str) – A short, alphanumeric, all-lowercase name for use in URLs. The slug has to be unique among the events of the same organizer.

  • live (bool) – Whether or not the shop is publicly accessible

  • currency (str) – The currency of all prices and payments of this event

  • date_from (datetime) – The datetime this event starts

  • date_to (datetime) – The datetime this event ends

  • presale_start (datetime) – No tickets will be sold before this date.

  • presale_end (datetime) – No tickets will be sold after this date.

  • location (str) – venue

  • plugins (str) – A comma-separated list of plugin names that are active for this event.

  • has_subevents (bool) – Enable event series functionality

  • sales_channels (list) – A list of sales channel identifiers, that this event is available for sale on

cache

Returns an ObjectRelatedCache object. This behaves equivalent to Django’s built-in cache backends, but puts you into an isolated environment for this event, so you don’t have to prefix your cache keys. In addition, the cache is being cleared every time the event or one of its related objects change.

get_date_from_display(tz=None, show_times=True, short=False) → str

Returns a formatted string containing the start date of the event with respect to the current locale and to the show_times setting.

get_date_range_display(tz=None, force_show_end=False, as_html=False) → str

Returns a formatted string containing the start date and the end date of the event with respect to the current locale and to the show_date_to setting. Times are not shown.

get_date_to_display(tz=None, show_times=True, short=False) → str

Returns a formatted string containing the start date of the event with respect to the current locale and to the show_times setting. Returns an empty string if show_date_to is False.

get_invoice_renderers() → dict

Returns a dictionary of initialized invoice renderers mapped by their identifiers.

get_mail_backend(timeout=None)

Returns an email server connection, either by using the system-wide connection or by returning a custom one based on the event’s settings.

get_payment_providers(cached=False) → dict

Returns a dictionary of initialized payment providers mapped by their identifiers.

get_plugins()

Returns the names of the plugins activated for this event as a list.

get_time_from_display(tz=None) → str

Returns a formatted string containing the start time of the event, ignoring the show_times setting.

property invoice_renderer

Returns the currently configured invoice renderer.

lock()

Returns a contextmanager that can be used to lock an event for bookings.

property payment_term_last

The last datetime of payments for this event.

property presale_has_ended

Is true, when presale_end is set and in the past.

property presale_is_running

Is true, when presale_end is not set or in the future and presale_start is not set or in the past.

class pretix.base.models.SubEvent(*args, **kwargs)

This model represents a date within an event series.

Parameters
  • event (Event) – The event this belongs to

  • active (bool) – Whether to show the subevent

  • is_public (bool) – Whether to show the subevent in lists

  • name (str) – This event’s full title

  • date_from (datetime) – The datetime this event starts

  • date_to (datetime) – The datetime this event ends

  • presale_start (datetime) – No tickets will be sold before this date.

  • presale_end (datetime) – No tickets will be sold after this date.

  • location (str) – venue

get_date_from_display(tz=None, show_times=True, short=False) → str

Returns a formatted string containing the start date of the event with respect to the current locale and to the show_times setting.

get_date_range_display(tz=None, force_show_end=False, as_html=False) → str

Returns a formatted string containing the start date and the end date of the event with respect to the current locale and to the show_date_to setting. Times are not shown.

get_date_to_display(tz=None, show_times=True, short=False) → str

Returns a formatted string containing the start date of the event with respect to the current locale and to the show_times setting. Returns an empty string if show_date_to is False.

get_time_from_display(tz=None) → str

Returns a formatted string containing the start time of the event, ignoring the show_times setting.

property presale_has_ended

Is true, when presale_end is set and in the past.

property presale_is_running

Is true, when presale_end is not set or in the future and presale_start is not set or in the past.

class pretix.base.models.Team(*args, **kwargs)

A team is a collection of people given certain access rights to one or more events of an organizer.

Parameters
  • name (str) – The name of this team

  • organizer (Organizer) – The organizer this team belongs to

  • members – A set of users who belong to this team

  • all_events (bool) – Whether this team has access to all events of this organizer

  • limit_events – A set of events this team has access to. Irrelevant if all_events is True.

  • can_create_events (bool) – Whether or not the members can create new events with this organizer account.

  • can_change_teams (bool) – If True, the members can change the teams of this organizer account.

  • can_manage_customers (bool) – If True, the members can view and change organizer-level customer accounts.

  • can_change_organizer_settings (bool) – If True, the members can change the settings of this organizer account.

  • can_change_event_settings (bool) – If True, the members can change the settings of the associated events.

  • can_change_items (bool) – If True, the members can change and add items and related objects for the associated events.

  • can_view_orders (bool) – If True, the members can inspect details of all orders of the associated events.

  • can_change_orders (bool) – If True, the members can change details of orders of the associated events.

  • can_checkin_orders (bool) – If True, the members can perform check-in related actions.

  • can_view_vouchers (bool) – If True, the members can inspect details of all vouchers of the associated events.

  • can_change_vouchers (bool) – If True, the members can change and create vouchers for the associated events.

exception DoesNotExist
exception MultipleObjectsReturned
class pretix.base.models.TeamAPIToken(*args, **kwargs)

A TeamAPIToken represents an API token that has the same access level as the team it belongs to.

Parameters
  • team (Team) – The team the person is invited to

  • name (str) – A human-readable name for the token

  • active (bool) – Whether or not this token is active

  • token (str) – The secret required to submit to the API

exception DoesNotExist
exception MultipleObjectsReturned
get_event_permission_set(organizer, event) → set

Gets a set of permissions (as strings) that a token holds for a particular event

Parameters
  • organizer – The organizer of the event

  • event – The event to check

Returns

set of permissions

get_events_with_any_permission()

Returns a queryset of events the token has any permissions to.

Returns

Iterable of Events

get_events_with_permission(permission, request=None)

Returns a queryset of events the token has a specific permissions to.

Parameters

request – Ignored, for compatibility with User model

Returns

Iterable of Events

get_organizer_permission_set(organizer) → set

Gets a set of permissions (as strings) that a token holds for a particular organizer

Parameters

organizer – The organizer of the event

Returns

set of permissions

has_event_permission(organizer, event, perm_name=None, request=None) → bool

Checks if this token is part of a team that grants access of type perm_name to the event event.

Parameters
  • organizer – The organizer of the event

  • event – The event to check

  • perm_name – The permission, e.g. can_change_teams

  • request – This parameter is ignored and only defined for compatibility reasons.

Returns

bool

has_organizer_permission(organizer, perm_name=None, request=None)

Checks if this token is part of a team that grants access of type perm_name to the organizer organizer.

Parameters
  • organizer – The organizer to check

  • perm_name – The permission, e.g. can_change_teams

  • request – This parameter is ignored and only defined for compatibility reasons.

Returns

bool

class pretix.base.models.EventMetaProperty(*args, **kwargs)

An organizer account can have EventMetaProperty objects attached to define meta information fields for its events. This information can be re-used for example in ticket layouts.

Parameters
  • organizer (Organizer) – The organizer this property is defined for.

  • name (Name of the property, used in various places) – Name

  • default (str) – Default value

exception DoesNotExist
exception MultipleObjectsReturned
full_clean(exclude=None, validate_unique=True)

Call clean_fields(), clean(), and validate_unique() on the model. Raise a ValidationError for any errors that occur.

class pretix.base.models.EventMetaValue(*args, **kwargs)

A meta-data value assigned to an event.

Parameters
  • event (Event) – The event this metadata is valid for

  • property (EventMetaProperty) – The property this value belongs to

  • value (str) – The actual value

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.SubEventMetaValue(*args, **kwargs)

A meta-data value assigned to a sub-event.

Parameters
  • event (Event) – The event this metadata is valid for

  • property (EventMetaProperty) – The property this value belongs to

  • value (str) – The actual value

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

Items

class pretix.base.models.Item(*args, **kwargs)

An item is a thing which can be sold. It belongs to an event and may or may not belong to a category. Items are often also called ‘products’ but are named ‘items’ internally due to historic reasons.

Parameters
  • event (Event) – The event this item belongs to

  • category (ItemCategory) – The category this belongs to. May be null.

  • name (str) – The name of this item

  • active (bool) – Whether this item is being sold.

  • description (str) – A short description

  • default_price (decimal.Decimal) – The item’s default price

  • tax_rate (decimal.Decimal) – The VAT tax that is included in this item’s price (in %)

  • admission (bool) – True, if this item allows persons to enter the event (as opposed to e.g. merchandise)

  • personalized (bool) – True, if attendee information should be collected for this ticket

  • picture (File) – A product picture to be shown next to the product description

  • available_from (datetime) – The date this product goes on sale

  • available_until (datetime) – The date until when the product is on sale

  • require_voucher (bool) – If set to True, this item can only be bought using a voucher.

  • hide_without_voucher (bool) – If set to True, this item is only visible and available when a voucher is used.

  • allow_cancel (bool) – If set to False, an order with this product can not be canceled by the user.

  • max_per_order (int) – Maximum number of times this item can be in an order. None for unlimited.

  • min_per_order (int) – Minimum number of times this item needs to be in an order if bought at all. None for unlimited.

  • checkin_attention (bool) – Requires special attention at check-in

  • original_price (decimal.Decimal) – The item’s “original” price. Will not be used for any calculations, will just be shown.

  • require_approval (bool) – If set to True, orders containing this product can only be processed and paid after approved by an administrator

  • sales_channels (bool) – Sales channels this item is available on.

  • issue_giftcard (bool) – If True, buying this product will give you a gift card with the value of the product’s price

exception DoesNotExist
exception MultipleObjectsReturned
check_quotas(ignored_quotas=None, count_waitinglist=True, subevent=None, _cache=None, include_bundled=False, trust_parameters=False, fail_on_no_quotas=False)

This method is used to determine whether this Item is currently available for sale.

Parameters
  • ignored_quotas – If a collection if quota objects is given here, those quotas will be ignored in the calculation. If this leads to no quotas being checked at all, this method will return unlimited availability.

  • include_bundled – Also take availability of bundled items into consideration.

  • trust_parameters – Disable checking of the subevent parameter and disable checking if any variations exist (performance optimization).

Returns

any of the return codes of Quota.availability().

Raises

ValueError – if you call this on an item which has variations associated with it. Please use the method on the ItemVariation object you are interested in.

is_available(now_dt: datetime.datetime = None) → bool

Returns whether this item is available according to its active flag and its available_from and available_until fields

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.ItemCategory(*args, **kwargs)

Items can be sorted into these categories.

Parameters
  • event (Event) – The event this category belongs to

  • name (str) – The name of this category

  • position (int) – An integer, used for sorting

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.ItemVariation(*args, **kwargs)

A variation of a product. For example, if your item is ‘T-Shirt’ then an example for a variation would be ‘T-Shirt XL’.

Parameters
  • item (Item) – The item this variation belongs to

  • value (str) – A string defining this variation

  • description (str) – A short description

  • active (bool) – Whether this variation is being sold.

  • default_price (decimal.Decimal) – This variation’s default price

  • original_price (decimal.Decimal) – The item’s “original” price. Will not be used for any calculations, will just be shown.

  • require_approval – If set to True, orders containing this variation can only be processed and paid after

approval by an administrator :type require_approval: bool

exception DoesNotExist
exception MultipleObjectsReturned
check_quotas(ignored_quotas=None, count_waitinglist=True, subevent=None, _cache=None, include_bundled=False, trust_parameters=False, fail_on_no_quotas=False) → Tuple[int, int]

This method is used to determine whether this ItemVariation is currently available for sale in terms of quotas.

Parameters
  • ignored_quotas – If a collection if quota objects is given here, those quotas will be ignored in the calculation. If this leads to no quotas being checked at all, this method will return unlimited availability.

  • count_waitinglist – If False, waiting list entries will be ignored for quota calculation.

Returns

any of the return codes of Quota.availability().

is_available(now_dt: datetime.datetime = None) → bool

Returns whether this item is available according to its active flag and its available_from and available_until fields

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.SubEventItem(*args, **kwargs)

This model can be used to change the price of a product for a single subevent (i.e. a date in an event series).

Parameters
  • subevent (SubEvent) – The date this belongs to

  • item (Item) – The item to modify the price for

  • price (Decimal) – The modified price (or None for the original price)

  • disabled (bool) – Disable the product for this subevent

  • available_until (datetime) – The date until when the product is on sale

  • available_from (datetime) – The date this product goes on sale

  • available_until – The date until when the product is on sale

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.SubEventItemVariation(*args, **kwargs)

This model can be used to change the price of a product variation for a single subevent (i.e. a date in an event series).

Parameters
  • subevent (SubEvent) – The date this belongs to

  • variation (ItemVariation) – The variation to modify the price for

  • price (Decimal) – The modified price (or None for the original price)

  • disabled (bool) – Disable the product for this subevent

  • available_until (datetime) – The date until when the product is on sale

  • available_from (datetime) – The date this product goes on sale

  • available_until – The date until when the product is on sale

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.ItemAddOn(*args, **kwargs)

An instance of this model indicates that buying a ticket of the time base_item allows you to add up to max_count items from the category addon_category to your order that will be associated with the base item.

Parameters
  • base_item (Item) – The base item the add-ons are attached to

  • addon_category (ItemCategory) – The category the add-on can be chosen from

  • min_count (int) – The minimal number of add-ons to be chosen

  • max_count (int) – The maximal number of add-ons to be chosen

  • position (int) – An integer used for sorting

exception DoesNotExist
exception MultipleObjectsReturned
clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

class pretix.base.models.Question(*args, **kwargs)

A question is an input field that can be used to extend a ticket by custom information, e.g. “Attendee age”. The answers are found next to the position. The answers may be found in QuestionAnswers, attached to OrderPositions/CartPositions. A question can allow one of several input types, currently:

  • a number (TYPE_NUMBER)

  • a one-line string (TYPE_STRING)

  • a multi-line string (TYPE_TEXT)

  • a boolean (TYPE_BOOLEAN)

  • a multiple choice option (TYPE_CHOICE and TYPE_CHOICE_MULTIPLE)

  • a file upload (TYPE_FILE)

  • a date (TYPE_DATE)

  • a time (TYPE_TIME)

  • a date and a time (TYPE_DATETIME)

Parameters
  • event (Event) – The event this question belongs to

  • question (str) – The question text. This will be displayed next to the input field.

  • type – One of the above types

  • required (bool) – Whether answering this question is required for submitting an order including items associated with this question.

  • items – A set of Items objects that this question should be applied to

  • ask_during_checkin (bool) – Whether to ask this question during check-in instead of during check-out.

  • hidden (bool) – Whether to only show the question in the backend

  • identifier (str) – An arbitrary, internal identifier

  • dependency_question (Question) – This question will only show up if the referenced question is set to dependency_value.

  • dependency_values (list[str]) – The values that dependency_question needs to be set to for this question to be applicable.

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.Quota(*args, **kwargs)

A quota is a “pool of tickets”. It is there to limit the number of items of a certain type to be sold. For example, you could have a quota of 500 applied to all of your items (because you only have that much space in your venue), and also a quota of 100 applied to the VIP tickets for exclusivity. In this case, no more than 500 tickets will be sold in total and no more than 100 of them will be VIP tickets (but 450 normal and 50 VIP tickets will be fine).

As always, a quota can not only be tied to an item, but also to specific variations.

Please read the documentation section on quotas carefully before doing anything with quotas. This might confuse you otherwise. https://docs.pretix.eu/en/latest/development/concepts.html#quotas

The AVAILABILITY_* constants represent various states of a quota allowing its items/variations to be up for sale.

AVAILABILITY_OK

This item is available for sale.

AVAILABILITY_RESERVED

This item is currently not available for sale because all available items are in people’s shopping carts. It might become available again if those people do not proceed to the checkout.

AVAILABILITY_ORDERED

This item is currently not available for sale because all available items are ordered. It might become available again if those people do not pay.

AVAILABILITY_GONE

This item is completely sold out.

Parameters
  • event (Event) – The event this belongs to

  • subevent (SubEvent) – The event series date this belongs to, if event series are enabled

  • name (str) – This quota’s name

  • size (int) – The number of items in this quota

  • items – The set of Item objects this quota applies to

  • variations – The set of ItemVariation objects this quota applies to

This model keeps a cache of the quota availability that is used in places where up-to-date data is not important. This cache might be out of date even though a more recent quota was calculated. This is intentional to keep database writes low. Currently, the cached values are written whenever the quota is being calculated throughout the system and the cache is at least 120 seconds old or if the new value is qualitatively “better” than the cached one (i.e. more free quota).

There’s also a cronjob that refreshes the cache of every quota if there is any log entry in the event that is newer than the quota’s cached time.

exception DoesNotExist
exception MultipleObjectsReturned
exception QuotaExceededException
availability(now_dt: datetime.datetime = None, count_waitinglist=True, _cache=None, allow_cache=False) → Tuple[int, int]

This method is used to determine whether Items or ItemVariations belonging to this quota should currently be available for sale.

Parameters
  • count_waitinglist – Whether or not take waiting list reservations into account. Defaults to True.

  • _cache – A dictionary mapping quota IDs to availabilities. If this quota is already contained in that dictionary, this value will be used. Otherwise, the dict will be populated accordingly.

  • allow_cache – Allow for values to be returned from the longer-term cache, see also the documentation of this model class. Only works if count_waitinglist is set to True.

Returns

a tuple where the first entry is one of the Quota.AVAILABILITY_ constants and the second is the number of available tickets.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

Carts and Orders

class pretix.base.models.Order(*args, **kwargs)

An order is created when a user clicks ‘buy’ on his cart. It holds several OrderPositions and is connected to a user. It has an expiration date: If items run out of capacity, orders which are over their expiration date might be canceled.

An order – like all objects – has an ID, which is globally unique, but also a code, which is shorter and easier to memorize, but only unique within a single conference.

Parameters
  • code (str) – In addition to the ID, which is globally unique, every order has an order code, which is shorter and easier to memorize, but is only unique within a single conference.

  • status

    The status of this order. One of:

    • STATUS_PENDING

    • STATUS_PAID

    • STATUS_EXPIRED

    • STATUS_CANCELED

  • event (Event) – The event this order belongs to

  • customer (Customer) – The customer this order belongs to

  • email (str) – The email of the person who ordered this

  • phone (str) – The phone number of the person who ordered this

  • testmode (bool) – Whether this is a test mode order

  • locale (str) – The locale of this order

  • secret (str) – A secret string that is required to modify the order

  • datetime (datetime) – The datetime of the order placement

  • expires (datetime) – The date until this order has to be paid to guarantee the fulfillment

  • total (decimal.Decimal) – The total amount of the order, including the payment fee

  • comment (str) – An internal comment that will only be visible to staff, and never displayed to the user

  • download_reminder_sent (boolean) – A field to indicate whether a download reminder has been sent.

  • require_approval (bool) – If set to True, this order is pending approval by an organizer

  • meta_info (str) – Additional meta information on the order, JSON-encoded.

  • sales_channel (str) – Identifier of the sales channel this order was created through.

exception DoesNotExist
exception MultipleObjectsReturned
property can_modify_answers

True if the user can change the question answers / attendee names that are related to the order. This checks order status and modification deadlines. It also returns False if there are no questions that can be answered.

property fees

Related manager for all non-canceled fees. Use all_fees instead if you want canceled positions as well.

property full_code

An order code which is unique among all events of a single organizer, built by concatenating the event slug and the order code.

property positions

Related manager for all non-canceled positions. Use all_positions instead if you want canceled positions as well.

save(**kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

send_mail(subject: Union[str, i18nfield.strings.LazyI18nString], template: Union[str, i18nfield.strings.LazyI18nString], context: Dict[str, Any] = None, log_entry_type: str = 'pretix.event.order.email.sent', user: pretix.base.models.auth.User = None, headers: dict = None, sender: str = None, invoices: list = None, auth=None, attach_tickets=False, position: Optional[pretix.base.models.orders.OrderPosition] = None, auto_email=True, attach_ical=False, attach_other_files: list = None)

Sends an email to the user that placed this order. Basically, this method does two things:

  • Call pretix.base.services.mail.mail with useful values for the event, locale, recipient and order parameters.

  • Create a LogEntry with the email contents.

Parameters
  • subject – Subject of the email

  • template – LazyI18nString or template filename, see pretix.base.services.mail.mail for more details

  • context – Dictionary to use for rendering the template

  • log_entry_type – Key to be used for the log entry

  • user – Administrative user who triggered this mail to be sent

  • headers – Dictionary with additional mail headers

  • sender – Custom email sender.

  • attach_tickets – Attach tickets of this order, if they are existing and ready to download

  • attach_ical – Attach relevant ICS files

  • position – An order position this refers to. If given, no invoices will be attached, the tickets will only be attached for this position and child positions, the link will only point to the position and the attendee email will be used if available.

property ticket_download_date

Returns the first date the tickets for this order can be downloaded or None if there is no restriction.

property user_cancel_allowed

Returns whether or not this order can be canceled by the user.

property user_change_allowed

Returns whether or not this order can be canceled by the user.

class pretix.base.models.AbstractPosition(*args, **kwargs)

A position can either be one line of an order or an item placed in a cart.

Parameters
  • subevent (SubEvent) – The date in the event series, if event series are enabled

  • item (Item) – The selected item

  • variation (ItemVariation) – The selected ItemVariation or null, if the item has no variations

  • datetime (datetime) – The datetime this item was put into the cart

  • expires (datetime) – The date until this item is guaranteed to be reserved

  • price (decimal.Decimal) – The price of this item

  • attendee_name_parts (str) – The parts of the attendee’s name, if entered.

  • attendee_name_cached (str) – The concatenated version of the attendee’s name, if entered.

  • attendee_email (str) – The attendee’s email, if entered.

  • voucher (Voucher) – A voucher that has been applied to this sale

  • meta_info (str) – Additional meta information on the position, JSON-encoded.

  • seat (Seat) – Seat, if reserved seating is used.

cache_answers(all=True)

Creates two properties on the object. (1) answ: a dictionary of question.id → answer string (2) questions: a list of Question objects, extended by an ‘answer’ property

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.OrderPosition(*args, **kwargs)

An OrderPosition is one line of an order, representing one ordered item of a specified type (or variation). This has all properties of AbstractPosition.

The default OrderPosition.objects manager only contains fees that are not canceled. If you want all objects, you need to use OrderPosition.all instead.

Parameters
  • order (Order) – The order this position is a part of

  • positionid (int) – A local ID of this position, counted for each order individually

  • tax_rate (Decimal) – The tax rate applied to this position

  • tax_rule (TaxRule) – The tax rule applied to this position

  • tax_value (Decimal) – The tax amount included in the price

  • secret (str) – The secret used for ticket QR codes

  • canceled (bool) – True, if this position is canceled and should no longer be regarded

  • pseudonymization_id (str) – The QR code content for lead scanning

exception DoesNotExist
exception MultipleObjectsReturned
property checkins

Related manager for all successful checkins. Use all_checkins instead if you want canceled positions as well.

refresh_from_db(using=None, fields=None)

Reload field values from the database. Similar to django’s implementation with adjustment for our method that forces us to create Transaction instances.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

send_mail(subject: str, template: Union[str, i18nfield.strings.LazyI18nString], context: Dict[str, Any] = None, log_entry_type: str = 'pretix.event.order.email.sent', user: pretix.base.models.auth.User = None, headers: dict = None, sender: str = None, invoices: list = None, auth=None, attach_tickets=False, attach_ical=False, attach_other_files: list = None)

Sends an email to the attendee. Basically, this method does two things:

  • Call pretix.base.services.mail.mail with useful values for the event, locale, recipient and order parameters.

  • Create a LogEntry with the email contents.

Parameters
  • subject – Subject of the email

  • template – LazyI18nString or template filename, see pretix.base.services.mail.mail for more details

  • context – Dictionary to use for rendering the template

  • log_entry_type – Key to be used for the log entry

  • user – Administrative user who triggered this mail to be sent

  • headers – Dictionary with additional mail headers

  • sender – Custom email sender.

  • attach_tickets – Attach tickets of this order, if they are existing and ready to download

  • attach_ical – Attach relevant ICS files

class pretix.base.models.OrderFee(*args, **kwargs)

An OrderFee object represents a fee that is added to the order total independently of the actual positions. This might for example be a payment or a shipping fee.

The default OrderFee.objects manager only contains fees that are not canceled. If you ant all objects, you need to use OrderFee.all instead.

Parameters
  • value (Decimal) – Gross price of this fee

  • order (Order) – Order this fee is charged with

  • fee_type (str) – The type of the fee, currently payment, shipping, service, giftcard, or other.

  • description (str) – A human-readable description of the fee

  • internal_type (str) – An internal string to group fees by, e.g. the identifier string of a payment provider

  • tax_rate (Decimal) – The tax rate applied to this fee

  • tax_rule (TaxRule) – The tax rule applied to this fee

  • tax_value (Decimal) – The tax amount included in the price

  • canceled (bool) – True, if this position is canceled and should no longer be regarded

exception DoesNotExist
exception MultipleObjectsReturned
refresh_from_db(using=None, fields=None)

Reload field values from the database. Similar to django’s implementation with adjustment for our method that forces us to create Transaction instances.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.OrderPayment(*args, **kwargs)

Represents a payment or payment attempt for an order.

Parameters
  • id – A globally unique ID for this payment

  • local_id (int) – An ID of this payment, counting from one for every order independently.

  • state (str) – The state of the payment, one of created, pending, confirmed, failed, canceled, or refunded.

  • amount (Decimal) – The payment amount

  • order (Order) – The order that is paid

  • created (datetime) – The creation time of this record

  • payment_date (datetime) – The completion time of this payment

  • provider (str) – The payment provider in use

  • info (str) – Provider-specific meta information (in JSON format)

  • fee (pretix.base.models.OrderFee) – The OrderFee object used to track the fee for this order.

  • process_initiated (bool) – Only for internal use inside pretix.presale to check which payments have started the execution process.

exception DoesNotExist
exception MultipleObjectsReturned
confirm(count_waitinglist=True, send_mail=True, force=False, user=None, auth=None, mail_text='', ignore_date=False, lock=True, payment_date=None, generate_invoice=True)

Marks the payment as complete. If possible, this also marks the order as paid if no further payment is required

Parameters
  • count_waitinglist (boolean) – Whether, when calculating quota, people on the waiting list should be taken into consideration (default: True).

  • force (boolean) – Whether this payment should be marked as paid even if no remaining quota is available (default: False).

  • ignore_date – Whether this order should be marked as paid even when the last date of payments is over.

  • send_mail (boolean) – Whether an email should be sent to the user about this event (default: True).

  • user – The user who performed the change

  • auth – The API auth token that performed the change

  • mail_text (str) – Additional text to be included in the email

Raises

Quota.QuotaExceededException – if the quota is exceeded and force is False

create_external_refund(amount=None, execution_date=None, info='{}')

This should be called to create an OrderRefund object when a refund has triggered by an external source, e.g. when a credit card payment has been refunded by the credit card provider.

Parameters
  • amount (Decimal) – Amount to refund. If not given, the full payment amount will be used.

  • execution_date (datetime) – Date of the refund. Defaults to the current time.

  • info (str) – Additional information, defaults to "{}".

Returns

OrderRefund

fail(info=None, user=None, auth=None, log_data=None)

Marks the order as failed and sets info to info, but only if the order is in created or pending state. This is equivalent to setting state to OrderPayment.PAYMENT_STATE_FAILED and logging a failure, but it adds strong database logging since we do not want to report a failure for an order that has just been marked as paid.

property full_id

The full human-readable ID of this payment, constructed by the order code and the local_id field with -P- in between. :return:

property info_data

This property allows convenient access to the data stored in the info attribute by automatically encoding and decoding the content as JSON.

payment_provider

Cached access to an instance of the payment provider in use.

property refunded_amount

The sum of all refund amounts in done, transit, or created states associated with this payment.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.OrderRefund(*args, **kwargs)

Represents a refund or refund attempt for an order.

Parameters
  • id – A globally unique ID for this refund

  • local_id (int) – An ID of this refund, counting from one for every order independently.

  • state (str) – The state of the refund, one of created, transit, external, canceled, failed, or done.

  • source – How this refund was started, one of buyer, admin, or external.

  • amount (Decimal) – The refund amount

  • order (Order) – The order that is refunded

  • created (datetime) – The creation time of this record

  • execution_date (datetime) – The completion time of this refund

  • provider (str) – The payment provider in use

  • info (dict) – Provider-specific meta information in JSON format

exception DoesNotExist
exception MultipleObjectsReturned
done(user=None, auth=None)

Marks the refund as complete. This does not modify the state of the order.

Parameters
  • user – The user who performed the change

  • auth – The API auth token that performed the change

property full_id

The full human-readable ID of this refund, constructed by the order code and the local_id field with -R- in between. :return:

property info_data

This property allows convenient access to the data stored in the info attribute by automatically encoding and decoding the content as JSON.

payment_provider

Cached access to an instance of the payment provider in use.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.Transaction(*args, **kwargs)

Transactions are a data structure that is redundant on the first sight but makes it possible to create good financial reporting.

To understand this, think of “orders” as something like a contractual relationship between the organizer and the customer which requires to customer to pay some money and the organizer to provide a ticket.

The Order, OrderPosition, and OrderFee models combined give a representation of the current contractual status of this relationship, i.e. how much and what is owed. The OrderPayment and OrderRefund models indicate the “other side” of the relationship, i.e. how much of the financial obligation has been met so far.

However, while OrderPayment and OrderRefund objects are “final” and no longer change once they reached their final state, Order, OrderPosition and OrderFee are highly mutable and can change at any time, e.g. if the customer moves their booking to a different day or a discount is applied retroactively.

Therefore those models can be used to answer the question “how many tickets of type X have been sold for my event as of today?” but they cannot accurately answer the question “how many tickets of type X have been sold for my event as of last month?” because they lack this kind of historical information.

Transactions help here because they are “immutable copies” or “modification records” of call positions and fees at the time of their creation and change. They only record data that is usually relevant for financial reporting, such as amounts, prices, products and dates involved. They do not record data like attendee names etc.

Even before the introduction of the Transaction Model pretix did store historical data for auditability in the LogEntry model. However, it’s almost impossible to do efficient reporting on that data.

Transactions should never be generated manually but only through the order.create_transactions() method which should be called within the same database transaction.

The big downside of this approach is that you need to remember to update transaction records every time you change or create orders in new code paths. The mechanism introduced in pretix.base.models._transactions as well as the save() methods of Order, OrderPosition and OrderFee intends to help you notice if you missed it. The only thing this doesn’t catch is usage of OrderPosition.objects.bulk_create (and likewise for bulk_update and OrderFee).

Parameters
  • id – ID of the transaction

  • order – Order the transaction belongs to

  • datetime – Date and time of the transaction

  • migrated – Whether this object was reconstructed because the order was created before transactions where introduced

  • positionid – Affected Position ID, in case this transaction represents a change in an order position

  • count – An amount, multiplicator for price etc. For order positions this can currently only be -1 or +1, for fees it can also be more in special cases

  • itemItem, in case this transaction represents a change in an order position

  • variationItemVariation, in case this transaction represents a change in an order position

  • subeventsubevent, in case this transaction represents a change in an order position

  • price – Price of the changed position

  • tax_rate – Tax rate of the changed position

  • tax_rule – Used tax rule

  • tax_value – Tax value in event currency

  • fee_type – Fee type code in case this transaction represents a change in an order fee

  • internal_type – Internal fee type in case this transaction represents a change in an order fee

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.CartPosition(*args, **kwargs)

A cart position is similar to an order line, except that it is not yet part of a binding order but just placed by some user in his or her cart. It therefore normally has a much shorter expiration time than an ordered position, but still blocks an item in the quota pool as we do not want to throw out users while they’re clicking through the checkout process. This has all properties of AbstractPosition.

Parameters
  • event (Event) – The event this belongs to

  • cart_id (str) – The user session that contains this cart position

exception DoesNotExist
exception MultipleObjectsReturned
class pretix.base.models.QuestionAnswer(*args, **kwargs)

The answer to a Question, connected to an OrderPosition or CartPosition.

Parameters
  • orderposition (OrderPosition) – The order position this is related to, or null if this is related to a cart position.

  • cartposition (CartPosition) – The cart position this is related to, or null if this is related to an order position.

  • question (Question) – The question this is an answer for

  • answer (str) – The actual answer data

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.Checkin(*args, **kwargs)

A check-in object is created when a ticket is scanned with our scanning apps.

exception DoesNotExist
exception MultipleObjectsReturned
save(**kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

Logging

class pretix.base.models.LogEntry(*args, **kwargs)

Represents a change or action that has been performed on another object in the database. This uses django.contrib.contenttypes to allow a relation to an arbitrary database object.

Parameters
  • datetime (datetime) – The timestamp of the logged action

  • user (User) – The user that performed the action

  • action_type (str) – The type of action that has been performed. This is used to look up the renderer used to describe the action in a human- readable way. This should be some namespaced value using dotted notation to avoid duplicates, e.g. "pretix.plugins.banktransfer.incoming_transfer".

  • data (str) – Arbitrary data that can be used by the log action renderer

exception DoesNotExist
exception MultipleObjectsReturned

Invoicing

class pretix.base.models.Invoice(*args, **kwargs)

Represents an invoice that is issued because of an order. Because invoices are legally required not to change, this object duplicates a lot of data (e.g. the invoice address).

Parameters
  • order (Order) – The associated order

  • event (Event) – The event this belongs to (for convenience)

  • organizer (Organizer) – The organizer this belongs to (redundant, for enforcing uniqueness)

  • invoice_no (int) – The human-readable, event-unique invoice number

  • is_cancellation (bool) – Whether or not this is a cancellation instead of an invoice

  • refers (Invoice) – A link to another invoice this invoice refers to, e.g. the canceled invoice in a cancellation

  • invoice_from (str) – The sender address

  • invoice_to (str) – The receiver address

  • full_invoice_no (str) – The full invoice number (for performance reasons only)

  • date (date) – The invoice date

  • locale (str) – The locale in which the invoice should be printed

  • introductory_text (str) – Introductory text for the invoice, e.g. for a greeting

  • additional_text (str) – Additional text for the invoice

  • payment_provider_text (str) – A payment provider specific text

  • footer_text (str) – A footer text, displayed smaller and centered on every page

  • foreign_currency_display (str) – A different currency that taxes should also be displayed in.

  • foreign_currency_rate (Decimal) – The rate of a foreign currency that the taxes should be displayed in.

  • foreign_currency_rate_date (date) – The date of the foreign currency exchange rates.

  • file (File) – The filename of the rendered invoice

exception DoesNotExist
exception MultipleObjectsReturned
delete(*args, **kwargs)

Deleting an Invoice would allow for the creation of another Invoice object with the same invoice_no as the deleted one. For various reasons, invoice_no should be reliably unique for an event.

property number

Returns the invoice number in a human-readable string with the event slug prepended.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class pretix.base.models.InvoiceLine(*args, **kwargs)

One position listed on an Invoice.

Parameters
  • invoice (Invoice) – The invoice this belongs to

  • description (str) – The item description

  • gross_value (decimal.Decimal) – The gross value

  • tax_value (decimal.Decimal) – The included tax (as an absolute value)

  • tax_rate (decimal.Decimal) – The applied tax rate in percent

  • tax_name (str) – The name of the applied tax rate

  • subevent (SubEvent) – The subevent this line refers to

  • event_date_from (datetime) – Event date of the (sub)event at the time the invoice was created

  • event_date_to (datetime) – Event end date of the (sub)event at the time the invoice was created

  • event_location (str) – Event location of the (sub)event at the time the invoice was created

  • item (Item) – The item this line refers to

  • variation (ItemVariation) – The variation this line refers to

  • attendee_name (str) – The attendee name at the time the invoice was created

exception DoesNotExist
exception MultipleObjectsReturned

Vouchers

class pretix.base.models.Voucher(*args, **kwargs)

A Voucher can reserve ticket quota or allow special prices.

Parameters
  • event (Event) – The event this voucher is valid for

  • subevent (SubEvent) – The date in the event series, if event series are enabled

  • code (str) – The secret voucher code

  • max_usages (int) – The number of times this voucher can be redeemed

  • redeemed (int) – The number of times this voucher already has been redeemed

  • min_usages (int) – The minimum number of times this voucher must be redeemed

  • valid_until (datetime) – The expiration date of this voucher (optional)

  • block_quota (bool) – If set to true, this voucher will reserve quota for its holder

  • allow_ignore_quota (bool) – If set to true, this voucher can be redeemed even if the event is sold out

  • price_mode (str) – Sets how this voucher affects a product’s price. Can be none, set, subtract or percent.

  • value (decimal.Decimal) – The value by which the price should be modified in the way specified by price_mode.

  • item (Item) – If set, the item to sell

  • variation (ItemVariation) – If set, the variation to sell

  • quota (Quota) – If set, the quota to choose an item from

  • comment (str) – An internal comment that will only be visible to staff, and never displayed to the user

  • tag (str) – Use this field to group multiple vouchers together. If you enter the same value for multiple vouchers, you can get statistics on how many of them have been redeemed etc.

Various constraints apply:

  • You need to either select a quota or an item

  • If you select an item that has variations but do not select a variation, you cannot set block_quota

exception DoesNotExist
exception MultipleObjectsReturned
applies_to(item: pretix.base.models.items.Item, variation: pretix.base.models.items.ItemVariation = None) → bool

Returns whether this voucher applies to a given item (and optionally a variation).

calculate_price(original_price: decimal.Decimal, max_discount: decimal.Decimal = None) → decimal.Decimal

Returns how the price given in original_price would be modified if this voucher is applied, i.e. replaced by a different price or reduced by a certain percentage. If the voucher does not modify the price, the original price will be returned.

clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

distinct_orders()

Return the list of orders where this voucher has been used. Each order will appear at most once.

is_active()

Returns True if a voucher has not yet been redeemed, but is still within its validity (if valid_until is set).

is_in_cart() → bool

Returns whether a cart position exists that uses this voucher.

is_ordered() → bool

Returns whether an order position exists that uses this voucher.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.