CGM_Public/pretix_original
2
0
Fork 1
mirror of https://github.com/pretix/pretix.git synced 2026-05-16 17:03:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Prepare for new docs, remove user docs as they move to own repo

Browse Source
This commit is contained in:
Raphael Michel
2025-01-30 22:45:03 +01:00
parent a6d1af01d2
commit 77c4cfbca8
137 changed files with 87 additions and 6467 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
doc/user/customers/index.rst
View File

@@ -1,210 +0,0 @@
.. _customers:
Customer accounts
=================
By default, pretix only offers guest checkout, i.e. ticket buyers do not sign up and sign back in, but create a new
checkout session every time. In some situations it may be convenient to allow ticket buyers to create
accounts that they can later log in to again. Working with customer accounts is even required for some advanced
use cases such as described in the :ref:`seasontickets` article.
Enabling customer accounts
--------------------------
To enable customer accounts, head to your organizer page in the backend and then select "Settings" → "General" →
"Customer accounts" and turn on the checkbox "Allow customers to create accounts".
Using the other settings on the same tab you can fine-tune how the customer account system behaves:
.. thumbnail:: ../../screens/organizer/edit_customer.png
:align: center
:class: screenshot
Allow customers to log in with email address and password
In all simple setups, this option should be checked. If this checkbox is removed, it is impossible to log in or
sign up unless you connect a SSO provider (see below).
Match orders based on email address
If this option is selected, customers will see orders made with their email address within their account even if
they did not make those orders while logged in.
Name format, Allowed titles
This controls how we'll ask your customers for their name, similar to the respective settings on event level.
Managing customer accounts
--------------------------
After customer accounts have been enabled, you will find a new menu option "Customer accounts" in the organizer-level
main menu. The first sub-item, "Customers", allows you to search and inspect the list of your customer accounts, as well
as to create a new customer account from the backend:
.. thumbnail:: ../../screens/organizer/customers.png
:align: center
:class: screenshot
If you click on a customer ID, you can see all details of this customer account, including registration information,
active memberships, past ticket orders, and account history:
.. thumbnail:: ../../screens/organizer/customer.png
:align: center
:class: screenshot
You can also perform various actions from this view, such as:
- Send a password reset link
- Change registration information
- Anonymize the customer account (does not anonymize connected orders)
When creating or changing a customer, you will be presented with the following form:
.. thumbnail:: ../../screens/organizer/customer_edit.png
:align: center
:class: screenshot
Most fields, such as name, e-mail address, phone number, and language should be self-explanatory. The following fields
might require some explanation:
Account active
If this checkbox is removed, the customer will not be able to log in.
External identifier
This field can be used to cross-reference your customer database with other sources. For example, if the customer
already has a number in another system, you can insert that number here. This can be especially powerful if you
use our API for synchronization with an external system.
Verified email address
This checkbox signifies whether you have verified that this customer in fact controls the given email address.
This will automatically be checked after a successful registration or after a successful password reset. Before it
is checked, the customer will not be able to log in. You should usually not modify this field manually.
Notes
Entries in this field will only be visible to you and your team, not to the customer.
Single-Sign-On (SSO)
--------------------
"Single-Sign-On" (SSO) is a technical term for a situation in which a person can log in to multiple systems using just
one login. This can be convenient if you have multiple applications that are exposed to your customers: They won't have
to remember multiple passwords or understand how your application landscape is structured, they can just always log in
with the same credentials whenever they see your brand.
In this scenario, pretix can be **either** the "SSO provider" **or** the "SSO client".
If pretix is the SSO provider, pretix will be the central source of truth for your customer accounts and your other
applications can connect to pretix to use pretix's login functionality.
If pretix is the SSO client, one of your existing systems will be the source of truth for the customer accounts and
pretix will use that system's login functionality.
All SSO support for customer accounts in pretix is currently built on the `OpenID Connect`_ standard, a modern and
widely accepted standard for SSO in all industries.
Connecting SSO clients (pretix as the SSO provider)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To connect an external application as a SSO client, go to "Customer accounts" → "SSO clients" → "Create a new SSO client"
in your organizer account.
.. thumbnail:: ../../screens/organizer/customer_ssoclient_add.png
:align: center
:class: screenshot
You will need to fill out the following fields:
Active
If this checkbox is removed, the SSO client can not be used.
Application name
The name of your external application, e.g. "digital event marketplace".
Client type
For a server-side application which is able to store a secret that will be inaccessible to end users, chose
"confidential". For a client-side application, such as many mobile apps, choose "public".
Grant type
This value depends on the OpenID Connect implementation of your software.
Redirection URIs
One or multiple URIs that the user might be redirected to after the successful or failed login.
Allowed access scopes
The types of data the SSO client may access about the customer.
After you submitted all data, you will receive a client ID as well as a client secret. The client secret is shown
in the green success message and will only ever be shown once. If you need it again, use the option "Invalidate old
client secret and generate a new one".
You will need the client ID and client secret to configure your external application. The application will also likely
need some other information from you, such as your **issuer URI**. If you use pretix Hosted and your organizer account
does not have a custom domain, your issuer will be ``https://pretix.eu/myorgname``, where ``myorgname`` is the short
form of your organizer account. If you use a custom domain, such as ``tickets.mycompany.net``, then your issuer will be
``https://tickets.mycompany.net``.
Technical details
"""""""""""""""""
We implement `OpenID Connect Core 1.0`_, except for some optional parts that do not make sense for pretix or bring no
additional value. For example, we do not currently support encrypted tokens, offline access, refresh tokens, or passing
request parameters as JWTs.
We implement the provider metadata section from `OpenID Connect Discovery 1.0`_. You can find the endpoint relative
to the issuer URI as described above, for example ``http://pretix.eu/demo/.well-known/openid-configuration``.
We implement all three OpenID Connect Core flows:
- Authorization Code Flow (response type ``code``)
- Implicit Flow (response types ``id_token token`` and ``id_token``)
- Hybrid Flow (response types ``code id_token``, ``code id_token token``, and ``code token``)
We implement the response modes ``query`` and ``fragment``.
We currently offer the following scopes: ``openid``, ``profile``, ``email``, ``phone``
As well as the following standardized claims: ``iss``, ``aud``, ``exp``, ``iat``, ``auth_time``, ``nonce``, ``c_hash``,
``at_hash``, ``sub``, ``locale``, ``name``, ``given_name``, ``family_name``, ``middle_name``, ``nickname``, ``email``,
``email_verified``, ``phone_number``.
The various endpoints are located relative to the issuer URI as described above:
- Authorization: ``<issuer>/oauth2/v1/authorize``
- Token: ``<issuer>/oauth2/v1/token``
- User info: ``<issuer>/oauth2/v1/userinfo``
- Keys: ``<issuer>/oauth2/v1/keys``
We currently do not reproduce their documentation here as they follow the OpenID Connect and OAuth specifications
without any special behavior.
Connecting SSO providers (pretix as the SSO client)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To connect an external application as a SSO provider, go to "Customer accounts" → "SSO providers" → "Create a new SSO provider"
in your organizer account.
.. thumbnail:: ../../screens/organizer/customer_ssoprovider_add.png
:align: center
:class: screenshot
The "Provider name" and "Login button label" is what we'll use to show the new login option to the user. For the actual
connection, we will require information such as the issuer URL, client ID, client secret, scope, and field (or claim)
names that you will receive from your SSO provider.
.. note::
If you want your customers to *only* use your SSO provider, it makes sense to turn off the "Allow customers to log in
with email address and password" settings option (see above).
Technical details
"""""""""""""""""
We assume that SSO providers fulfill the following requirements:
- Implementation according to `OpenID Connect Core 1.0`_.
- Published meta-data document at ``<issuer>/.well-known/openid-configuration`` as specified in `OpenID Connect Discovery 1.0`_.
- Support for Authorization code flow (``response_type=code``) with ``response_mode=query``.
- Support for client authentication using client ID and client secret and without public key cryptography.
.. _OpenID Connect: https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)
.. _OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html
.. _OpenID Connect Discovery 1.0: https://openid.net/specs/openid-connect-discovery-1_0.html

99
doc/user/events/create.rst
View File

@@ -1,99 +0,0 @@
.. _event_create:
Creating an event
=================
After you have created an organizer account, the next step is to create your event. An event is the basic object in
pretix that everything is organized around. One event corresponds to one ticket shop with all its products, quotas,
orders and settings.
To create an event, you can click the "Create a new event" tile on your dashboard or the button above the list of
events. You will then be presented with the first step of event creation:
.. thumbnail:: ../../screens/event/create_step1.png
:align: center
:class: screenshot
Here, you first need to decide for the organizer the event belongs to. You will not be able to change this
association later. This will determine default settings for the event, as well as access control to the event's
settings.
Second, you need to select the languages that the ticket shop should be available in. You can change this setting
later, but if you select it correctly now, it will automatically ask you for all descriptions in the respective
languages starting from the next step.
Last on this page, you can decide if this event represents an event series. In this cases, the event will turn into
multiple events included in once, meaning that you will get one combined ticket shop for multiple actual events. This
is useful if you have a large number of events that are very similar to each other and that should be sold together
(i.e. users should be able to buy tickets for multiple events at the same time). Those single events can differ in
available products, quotas, prices and some meta information, but most settings need to be the same for all of them.
We recommend to use this feature only if you really know that you need it and if you really run a lot of events, not if
you run e.g. a yearly conference. You can read more on this feature :ref:`here <subevents>`.
Once you set these values, you can proceed to the next step:
.. thumbnail:: ../../screens/event/create_step2.png
:align: center
:class: screenshot
In this step, you will be asked more detailed questions about your event. In particular, you can fill in the
following fields:
Name
This is the public name of your event. It should be descriptive and tell both you and the user which event you are
dealing with, but should still be concise. You probably know how your event is named already ;)
Short form
This will be used in multiple places. For example, the URL of your ticket shop will include this short form of
your event name, but it will also be the default prefix e.g. for invoice numbers. We recommend to use some natural
abbreviation of your event name, maybe together with a date, of no more than 10 characters. This is the only value
on this page that can't be changed later.
Event start time
The date and time that your event starts at. You can later configure settings to hide the time, if you don't want
to show that.
Event end time
The date and time your event ends at. You can later configure settings to hide this value completely -- or you can
just leave it empty. It's optional!
Location
This is the location of your event in a human-readable format. We will show this on the ticket shop frontpage, but
it might also be used e.g. in Wallet tickets.
Event currency
This is the currency all prices and payments in your shop will be handled in.
Sales tax rate
If you need to pay a form of sales tax (also known as VAT in many countries) on your products, you can set a tax rate
in percent here that will be used as a default later. After creating your event, you can also create multiple tax
rates or fine-tune the tax settings.
Default language
If you selected multiple supported languages in the previous step, you can now decide which one should be
displayed by default.
Start of presale
If you set this date, no ticket will be sold before this date. We normally recommend not to set this date during
event creation because it will make testing your shop harder.
End of presale
If you set this date, no ticket will be sold after this date.
If all of this is set, you can proceed to the next step. If this is your first event, there will not be a next step
and you are done! If you have already created events before, you will be asked if you want to copy settings from one
of them:
.. thumbnail:: ../../screens/event/create_step3.png
:align: center
:class: screenshot
If you do so, all products, categories, quotas and most settings of the other event will be taken over. You should
still review them if they make sense for your new event, but it could save you a lot of work. After this step, your
event is created successfully:
.. thumbnail:: ../../screens/event/create_step4.png
:align: center
:class: screenshot
You can now fine-tune all settings to your liking, publish your event and start selling tickets!

55
doc/user/events/display.rst
View File

@@ -1,55 +0,0 @@
Display settings
================
The settings at "Settings" → "Display" allow you to customize the appearance of your ticket shop.
.. thumbnail:: ../../screens/event/settings_display.png
:align: center
:class: screenshot
The upper part of the page contains settings that you always need to set specifically for your event. Those are
currently:
Logo image
This logo will be shown as a banner above your shop. If you set it, the event name and date will no longer be
displayed by the shop, so we suggest to include them in the image yourself. The maximal height of the image is
120 pixels and if you want to use the full width, make your image 1140 pixels wide. If the user's screen is
smaller, the logo will be scaled down automatically, so it should still be legible at smaller sizes.
Frontpage text
This text will be shown on the front page of your ticket shop, above the list of products. You can use it to explain
your product types, give more information on the event or for other general notices.
You can use :ref:`Markdown syntax <markdown-guide>` in this field.
Voucher explanation
This text will be shown above the voucher input box. You can use it to explain how to obtain a voucher and use it.
Show variations of a product expanded by default
If this is not checked, a product with variations will be shown as one row in the show by default and will expand
into multiple rows once it is clicked on. With this box checked, the variations will be shown as multiple rows
right from the beginning.
Ask search engines not to index the ticket shop
If this is checked, we will set a HTML meta attribute asking search engines by Google not to put this ticket shop
into their searchable index.
The lower part of the page contains settings that you can **either** set on organizer-level for all your events **or**
override for this single event individually. Those are:
Primary color
This color will be used for links, buttons, and other design elements throughout your shop and emails sent to your
customers. We suggest not choosing something to light, since text in that color should be readable on a white
background and white text should be readable on a background of this color.
Accent color for success
This color will be used for success messages. We suggest to choose a dark shade of green.
Accent color for errors
This color will be used for error messages. We suggest to choose a dark shade of red.
Font
Choose one of multiple fonts to use for your web shop.
.. note:: Both the color and font settings can take a few seconds up to a few minutes before they become active on your
shop.

216
doc/user/events/email.rst
View File

@@ -1,216 +0,0 @@
E-mail settings
===============
The settings at "Settings" → "E-mail" allow you to customize the emails that pretix sends to the participants of your
event.
.. thumbnail:: ../../screens/event/settings_email.png
:align: center
:class: screenshot
The page is separated into four parts: "E-mail settings", "E-mail design", "E-mail content" and "SMTP settings".
We will explain all of them in detail on this page.
E-mail settings
---------------
The upper part of the page contains settings that are relevant for the generation of all e-mails alike. Those are
currently:
Subject prefix
This text will be prepended to the subject of all e-mails that are related to your event. For example, if you
set this to "dc2018" all subjects will be formatted like "[dc2018] Your payment was successful".
Sender address
All e-mails will be sent with this address in the "From" field. If you use an email address at a custom domain,
we strongly recommend to use the SMTP settings below as well, otherwise your e-mails might be detected as spam
due to the `Sender Policy Framework`_ and similar mechanisms.
Sender name
This is the name associated with the sender address. By default, this is your event name.
Signature
This text will be appended to all e-mails in form of a signature. This might be useful e.g. to add your contact
details or any legal information that needs to be included with the e-mails.
Bcc address
This email address will receive a copy of every event-related email.
Attach calendar files
With this option, every order confirmation mail will include an ics file with name, date and location of
your event. It can be imported into many digital calendars.
Sales Channels for Checkout Emails
When you are using multiple sales channel, you may want to decide that mails for order and payment confirmation
are only to be sent for some sales channels. For orders created through the default online shop, these emails
must always be send. A similar option is available for ticket download reminders.
E-mail design
-------------
In this part, you can choose and preview the layout of your emails. More layouts can be added by pretix plugins.
E-mail content
--------------
The next part of the page allows you to customize the exact texts of all e-mails sent by the system automatically.
You can click on the different boxes to expand them and see the texts.
Within the texts, you can use placeholders that will later by replaced by values depending on the event or order. Below
every text box is a list of supported placeholders, but currently the following are defined (not every placeholder
is valid in every text):
============================== ===============================================================================
Placeholder Description
============================== ===============================================================================
event The event name
event_slug The event's short form
code In case of the waiting list, the voucher code to redeem
currency The currency used for the event (three-letter code)
total The order's total value
total_with_currency The order's total value with a localized currency sign
refund_amount (For cancellation emails) The amount of money that will be refunded, including
the currency
payment_info Information text specific to the payment method (e.g. banking details)
url An URL pointing to the download/status page of the order
url_info_change An URL pointing to the page of the order that can be used to change ticket
information
url_products_change An URL pointing to the page of the order that can be used to change the products
in the order
url_cancel An URL pointing to the page of the order that can be used to cancel the order
name, name_* Any name that can be used to address the recipient (e.g. name from invoice address,
name from first ticket, …)
invoice_name, invoice_name_* The name field of the invoice address
invoice_company The company field of the invoice address
attendee_name, attendee_name_* The name of the attendee represented by the ticket
expire_date The order's expiration date
comment When rejecting an order, this will contain the reason for the rejection
date The same as ``expire_date``, but in a different e-mail (for backwards
compatibility)
orders A list of orders including links to their status pages, specific to the "resend
link (requested by user)" e-mail
hours In case of the waiting list, the number of hours the voucher code is valid
product In case of the waiting list, the product that has become available
voucher_list When sending out vouchers in bulk, this will be replaced with the list of
vouchers
============================== ===============================================================================
The different e-mails are explained in the following:
Placed Order
This e-mail is sent out to every order directly after the order has been received, except if the order total
is zero (see below). It should specify that/how the order is to be paid.
Paid Order
This e-mail is sent out as soon as the payment for an order has been received and should give the customer
more information on how to proceed, e.g. by downloading their ticket.
Free Order
This e-mail is sent out instead of "Placed Order" and "Paid Order" if the order total is zero. It therefore should
tell the same information, except asking the customer for completing their payment.
Resend link
Sent by admin
This e-mail will be sent out if you click the "Resend link" next to the e-mail address field on the order detail
page. It should include the link to the order and can be sent to users e.g. if they lost their original e-mails.
Requested by user
Customers can also request a link to all orders they created using their e-mail address themselves by filling
out a form on the website. In this case, they will receive an e-mail containing a list of all orders they created
with the respective links.
Order changed
This e-mail is sent out if you change the content of the order and choose to notify the user about it.
Payment reminder
This e-mail is sent out a certain number of days before the order's expiry date. You can specify the number of days
before the expiry date that this should happen and the e-mail will only ever be sent if you do specify such a
number. The text should ask the customer to complete the payment, tell the options on how to do so and the
consequences if no payment is received (ticket gone, depending on your other settings). You should also include
a way to contact you in case of questions.
Waiting list notification
If you enable the waiting list feature, this is the mail that will be sent out if a ticket is assigned to a person on
the waiting list. It should include the voucher that needs to be redeemed to get the free spot and tell how long
that voucher is valid and where to redeem it.
Order canceled
This e-mail is sent to a customer if their order has been canceled.
Order custom mail
You can use pretix' admin interface to directly send an e-mail with a custom text to the customer of a specific
order. In this case, this will be the default text and might save you time by not having to re-type all of it every
time.
Reminder to download tickets
If you want, you can configure an email that will be send out a number of days before your event to remind
attendees to download their tickets. The e-mail should include a link to the ticket download. This e-mail will only
ever be sent if you specify a number of days.
Order approval process
If you configure one of your products to "require approval", orders of that product will not immediately be confirmed
but only after you approved them manually. In this case, the following e-mail templates will be sent out.
Received order
After an order has been received, this e-mail will be sent automatically instead of the "order placed" e-mail from
above.
Approved order
This e-mail will be sent after you manually approved an order. This should include instructions to pay for the order,
which is why this will only be used for a paid order. For a free order, the "free order" e-mail from above will
be sent.
Denied order
This e-mail will be sent out to customers when their order has been denied.
SMTP settings
-------------
If you want to send your e-mails via your own e-mail address, we strongly recommend to use SMTP for this purpose.
SMTP is a protocol that is used by e-mail clients to communicate with e-mail servers. Using SMTP, pretix can talk to
your e-mail service provider the same way that e.g. the e-mail app on your phone can.
Your e-mail provider will most likely have a document that tells you the settings for the various fields to fill in
here (hostname, port, username, password, encryption).
With the checkbox "Use custom SMTP server" you can turn using your SMTP server on or off completely. With the
button "Save and test custom SMTP connection", you can test if the connection and authentication to your SMTP server
succeeds, even before turning that checkbox on.
Spam issues
-----------
If you use an email address of your own domain as a sender address and do not use a custom SMTP server, it is very
likely that at least some of your emails will go to the spam folders of their recipients. We **strongly recommend**
to use your organization's SMTP server in this case, making your email really come from your organization. If you don't
want that or cannot do that, you should add the pretix application server to your SPF record.
If you are using our hosted service at pretix.eu, you can add the following to your SPF record::
include:_spf.pretix.eu
A complete record could look like this::
v=spf1 a mx include:_spf.pretix.eu ~all
Make sure to read up on the `SPF specification`_.
If you want to authenticate your emails with `DKIM`_, set up a ``CNAME`` record for the subdomain ``pretix._domainkey``
pointing to ``dkim.pretix.eu``::
pretix._domainkey.mydomain.com. CNAME dkim.pretix.eu.
Then, please contact support@pretix.eu and we will enable DKIM for your domain on our mail servers.
For senders with larger volumes, Google Mail also requires you to have a `DMARC`_ policy (that may however be ``p=none``).
.. note:: Many SMTP servers impose rate limits on the sent emails, such as a maximum number of emails sent per hour.
These SMTP servers are often not suitable for use with pretix, in case you want to send an email to many
hundreds or thousands of ticket buyers. Depending on how the rate limit is implemented, emails might be lost
in this case, as pretix only retries email delivery for a certain time period.
.. _DKIM: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
.. _Sender Policy Framework: https://en.wikipedia.org/wiki/Sender_Policy_Framework
.. _SPF specification: http://www.open-spf.org/SPF_Record_Syntax
.. _DMARC: https://en.wikipedia.org/wiki/DMARC

73
doc/user/events/giftcards.rst
View File

@@ -1,73 +0,0 @@
.. spelling:word-list::
Warengutschein
Wertgutschein
.. _giftcards:
Gift cards
==========
Gift cards, also known as "gift coupons" or "gift certificates" are a mechanism that allows you to sell tokens that
can later be used to pay for tickets.
Gift cards are very different feature than **vouchers**. The difference is:
* Vouchers can be used to give a discount. When a voucher is used, the price of a ticket is reduced by the configured
discount and sold at a lower price. They therefore reduce both revenue as well as taxes. Vouchers (in pretix) are
always specific to a certain product in an order. Vouchers are usually not sold but given out as part of a
marketing campaign or to specific groups of people. Vouchers in pretix are bound to a specific event.
* Gift cards are not a discount, but rather a means of payment. If you buy a €20 ticket with a €10 gift card, it is
still a €20 ticket and will still count towards your revenue with €20. Gift cards are usually bought for the money
that they are worth. Gift cards in pretix can be used across events (and even organizers).
Selling gift cards
------------------
Selling gift cards works like selling every other type of product in pretix: Create a new product, then head to
"Additional settings" and select the option "This product is a gift card". Whenever someone buys this product and
pays for it, a new gift card will be created.
In this case, the gift card code corresponds to the "ticket secret" in the PDF ticket. Therefore, if selling gift cards,
you can use ticket downloads just as with normal tickets and use our ticket editor to create beautiful gift certificates
people can give to their loved ones.
Of course, you can use pretix' flexible options to modify your product. For example, you can configure that the customer
can freely choose the price of the gift card.
.. note::
pretix currently does not support charging sales tax or VAT when selling gift cards, but instead charges VAT on
the full price when the gift card is redeemed. This is the correct behavior in Germany and some other countries for
gift cards which are not bound to a very specific service ("Warengutschein"), but instead to a monetary amount
("Wertgutschein").
.. note::
The ticket PDF will not contain the correct gift card code before the order has been paid, so we recommend not
selling gift cards in events where tickets are issued before payments arrive.
Accepting gift cards
--------------------
All your events have have the payment provider "Gift card" enabled by default, but it will only show up in the ticket
shop once the very first gift card has been issued on your organizer account. Of course, you can turn off gift card
payments if you do not want them for a specific event.
If gift card payments are enabled, buyers will be able to select "Gift card" as a payment method during checkout. If
a gift card with a value less than the order total is used, the buyer will be asked to select a second payment method
for the remaining payment. If a gift card with a value greater than the order total is used, the surplus amount
remains on the gift card and can be used in a different purchase.
If it possible to accept gift cards across organizer accounts. To do so, you need to have access to both organizer
accounts. Then, you will see a configuration section at the bottom of the "Gift cards" page of your organizer settings
where you can specify which gift cards should be accepted.
Manually issuing or using gift cards
------------------------------------
Of course, you can also issue or redeem gift cards manually through our backend using the "Gift cards" menu item in your
organizer profile or using our API. These gift cards will be tracked by pretix, but do not correspond to any purchase
within pretix. You will therefore need to account for them in your books separately.

20
doc/user/events/guides/earlybird_dates.rst
View File

@@ -1,20 +0,0 @@
Use case: Early-bird tiers based on dates
-----------------------------------------
Let's say you run a conference that has the following pricing scheme:
* 12 to 6 months before the event: € 450
* 6 to 3 months before the event: € 550
* closer than 3 months to the event: € 650
Of course, you could just set up one product and change its price at the given dates manually, but if you want to set
this up automatically, here's how:
Create three products (e.g. "super early bird", "early bird", "regular ticket") with the respective prices and one shared
quota of your total event capacity. Then, set the **available from** and **available until** configuration fields of
the products to automatically turn them on and off based on the current date.
If you're in an event series, this will likely not help you since these dates would need to be the same for all dates
in your series. As an alternative, you can go to the "Dates" section of your event series, select one or more dates,
and scroll down to the "product settings" section. Here, you can also define availability times for individual products
just for this date individually.

47
doc/user/events/guides/earlybird_numbers.rst
View File

@@ -1,47 +0,0 @@
Use case: Early-bird tiers based on ticket numbers
--------------------------------------------------
Let's say you run a conference with 400 tickets that has the following pricing scheme:
* First 100 tickets ("super early bird"): € 450
* Next 100 tickets ("early bird"): € 550
* Remaining tickets ("regular"): € 650
First of all, create three products:
* "Super early bird ticket"
* "Early bird ticket"
* "Regular ticket"
Then, create three quotas:
* "Super early bird" with a **size of 100** and the "Super early bird ticket" product selected. At "Advanced options",
select the box "Close this quota permanently once it is sold out".
* "Early bird and lower" with a **size of 200** and both of the "Super early bird ticket" and "Early bird ticket"
products selected. At "Advanced options", select the box "Close this quota permanently once it is sold out".
* "All participants" with a **size of 400**, all three products selected and **no additional options**.
Next, modify the product "Regular ticket". In the section "Availability", you should look for the option "Only show
after sellout of" and select your quota "Early bird and lower". Do the same for the "Early bird ticket" with the quota
"Super early bird ticket".
This will ensure the following things:
* Each ticket level is only visible after the previous level is sold out.
* As soon as one level is really sold out, it's not coming back, because the quota "closes", i.e. locks in place.
* By creating a total quota of 400 with all tickets included, you can still make sure to sell the maximum number of
tickets, even if e.g. early-bird tickets are canceled.
Optionally, if you want to hide the early bird prices once they are sold out, go to "Settings", then "Display" and
select "Hide all products that are sold out". Of course, it might be a nice idea to keep showing the prices to remind
people to buy earlier next time ;)
Please note that there might be short time intervals where the prices switch back and forth: When the last early bird
tickets are in someone's cart (but not yet sold!), the early bird tickets will show as "Reserved" and the regular
tickets start showing up. However, if the customers holding the reservations do not complete their order,
the early bird tickets will become available again. This is not avoidable if we want to prevent malicious users
from blocking all the cheap tickets without an actual sale happening.

44
doc/user/events/guides/groups.rst
View File

@@ -1,44 +0,0 @@
Use case: Group discounts
-------------------------
Often times, you want to give discounts for whole groups attending your event.
Automatic discounts
"""""""""""""""""""
pretix can automatically grant discounts if a certain condition is met, such as a specific group size. To set this up,
head to **Products**, **Discounts** in the event navigation and **Create a new discount**. You can choose a name so you
can later find this again. You can also optionally restrict the discount to a specific time frame or a specific sales
channel.
Next, either select **Apply to all products** or create a selection of products that are eligible for the discount.
For a **percentual group discount** similar to "if you buy at least 5 tickets, you get 20 percent off", set
**Minimum number of matching products** to "5" and **Percentual discount on matching products** to "20.00".
For a **buy-X-get-Y discount**, e.g. "if you buy 5 tickets, you get one free", set
**Minimum number of matching products** to "5", **Percentual discount on matching products** to "100.00", and
**Apply discount only to this number of matching products** to "1".
Fixed group packages
""""""""""""""""""""
If you want to sell group tickets in fixed sizes, e.g. a table of eight at your gala dinner, you can use product bundles.
Assuming you already set up a ticket for admission of single persons, you then set up a second product **Table (8 persons)**
with a discounted full price. Then, head to the **Bundled products** tab of that product and add one bundle configuration
to include the single admission product **eight times**. Next, create an unlimited quota mapped to the new product.
This way, the purchase of a table will automatically create eight tickets, leading to a correct calculation of your total
quota and, as expected, eight persons on your check-in list. You can even ask for the individual names of the persons
during checkout.
Minimum order amount
""""""""""""""""""""
If you want to promote discounted group tickets in your price list, you can also do so by creating a special
**Group ticket** at the reduced per-person price and set the **Minimum amount per order** option of the ticket to the minimal
group size.
For more complex use cases, you can also use add-on products that can be chosen multiple times.
This way, your ticket can be bought an arbitrary number of times – but no less than the given minimal amount per order.

21
doc/user/events/guides/mixed_taxation.rst
View File

@@ -1,21 +0,0 @@
Use case: Mixed taxation
------------------------
Let's say you are a charitable organization in Germany and are allowed to charge a reduced tax rate of 7% for your educational event. However, your event includes a significant amount of food, you might need to charge a 19% tax rate on that portion. For example, your desired tax structure might then look like this:
* Conference ticket price: € 450 (incl. € 150 for food)
* incl. € 19.63 VAT at 7%
* incl. € 23.95 VAT at 19%
You can implement this in pretix using product bundles. In order to do so, you should create the following two products:
* Conference ticket at € 450 with a 7% tax rule
* Conference food at € 150 with a 19% tax rule and the option "**Only sell this product as part of a bundle**" set
In addition to your normal conference quota, you need to create an unlimited quota for the food product.
Then, head to the **Bundled products** tab of the "conference ticket" and add the "conference food" as a bundled product with a **designated price** of € 150.
Once a customer tries to buy the € 450 conference ticket, a sub-product will be added and the price will automatically be split into the two components, leading to a correct computation of taxes.

78
doc/user/events/guides/packages.rst
View File

@@ -1,78 +0,0 @@
Use case: Discounted packages
-----------------------------
Imagine you run a trade show that opens on three consecutive days and you want to have the following pricing:
* Single day: € 10
* Any two days: € 17
* All three days: € 25
In this case, there are multiple different ways you could set this up with pretix.
Option A: Combination products
""""""""""""""""""""""""""""""
With this option, you just set up all the different combinations someone could by as a separate product. In this case, you would need 7 products:
* Day 1 pass
* Day 2 pass
* Day 3 pass
* Day 1+2 pass
* Day 2+3 pass
* Day 1+3 pass
* All-day pass
Then, you create three quotas, each one with the maximum capacity of your venue on any given day:
* Day 1 quota, linked to "Day 1 pass", "Day 1+2 pass", "Day 1+3 pass", and "All-day pass"
* Day 2 quota, linked to "Day 2 pass", "Day 1+2 pass", "Day 2+3 pass", and "All-day pass"
* Day 3 quota, linked to "Day 3 pass", "Day 2+3 pass", "Day 1+3 pass", and "All-day pass"
This way, every person gets exactly one ticket that they can use for all days that they attend. You can later set up check-in lists appropriately to make sure only tickets valid for a certain day can be scanned on that day.
The benefit of this option is that your product structure and order structure stays very simple. However, the two-day packages scale badly when you need many products.
We recommend this setup for most setups in which the number of possible combinations does not exceed the number of parts (here: number of days) by much.
Option B: Add-ons and bundles
"""""""""""""""""""""""""""""
We can combine the two features "product add-ons" and "product bundles" to set this up in a different way. Here, you would create the following five products:
* Day 1 pass in a category called "Day passes"
* Day 2 pass in a category called "Day passes"
* Day 3 pass in a category called "Day passes"
* Two-day pass
* All-day pass
This time, you will need five quotas:
* Day 1 quota, linked to "Day 1 pass"
* Day 2 quota, linked to "Day 2 pass"
* Day 3 quota, linked to "Day 3 pass"
* Two-day pass quota, linked to "Two-day pass" (can be unlimited)
* All-day pass quota, linked to "All-day pass" (can be unlimited)
Then, you open the "Add-On" tab in the settings of the **Two-day pass** product and create a new add-on configuration specifying the following options:
* Category: "Day passes"
* Minimum number: 2
* Maximum number: 2
* Add-Ons are included in the price: Yes
This way, when buying a two-day pass, the user will be able to select *exactly* two days for free, which will then be added to the cart. Depending on your specific configuration, the user will now receive *two separate* tickets, one for each day.
For the all-day pass, you open the "Bundled products" tab in the settings of the **All-day pass** product and add **three** new bundled items with the following options:
* Bundled product: "Day 1/2/3"
* Bundled variation: None
* Count: 1
* Designated price: 0
This way, when buying an all-day pass, three free day passes will *automatically* be added to the cart. Depending on your specific configuration, the user will now receive *three separate* tickets, one for each day.
This approach makes your order data more complicated, since e.g. someone who buys an all-day pass now technically bought **four products**. However, this option allows for more flexibility when you have lots of options to choose from.
.. tip::
Depending on the packages you offer, you **might not need both the add-on and the bundle feature**, i.e. you only need the add-on feature for the two-day pass and only the bundle feature for the all-day pass. You could also set up the two-day pass like we showed here, but the all-day pass like in option A!

13
doc/user/events/guides/pricelevels.rst
View File

@@ -1,13 +0,0 @@
Use case: Multiple price levels
-------------------------------
Imagine you're running a concert with general admission that sells a total of 200 tickets for two prices:
* Regular: € 25.00
* Students: € 19.00
You can either set up two different products called e.g. "Regular ticket" and "Student ticket" with the respective prices, or two variations within the same product. In this simple case, it really doesn't matter.
In addition, you will need quotas. If you do not care how many of your tickets are sold to students, you should set up just **one quota** of 200 called e.g. "General admission" that you link to **both products**.
If you want to limit the number of student tickets to 50 to ensure a certain minimum revenue, but do not want to limit the number of regular tickets artificially, we suggest you to create the same quota of 200 that is linked to both products, and then create a **second quota** of 50 that is only linked to the student ticket. This way, the system will reduce both quotas whenever a student ticket is sold and only the larger quota when a regular ticket is sold.

28
doc/user/events/guides/restricted_audience.rst
View File

@@ -1,28 +0,0 @@
Use case: Restricted audience
-----------------------------
Not all events are for everyone. Sometimes, there is a good reason to restrict access to your event or parts of your event only to a specific, invited group. There's two ways to implement this with pretix:
Option A: Required voucher codes
""""""""""""""""""""""""""""""""
If you check the option "**This product can only be bought using a voucher**" of one or multiple products, only people holding an applicable voucher code will be able to buy the product.
You can then generate voucher codes for the respective product and send them out to the group of possible attendees. If the recipients should still be able to choose between different products, you can create an additional quota and map the voucher to that quota instead of the products themselves.
There's also the second option "**This product will only be shown if a voucher matching the product is redeemed**". In this case, the existence of the product won't even be shown before a voucher code is entered – useful for a VIP option in a shop where you also sell other products to the general public. Please note that this option does **not** work with vouchers assigned to a quota, only with vouchers assigned directly to the product.
This option is appropriate if you know the group of people beforehand, e.g. members of a club, and you can mail them their access codes.
Option B: Order approvals
"""""""""""""""""""""""""
If you do not know your audience already, but still want to restrict it to a certain group, e.g. people with a given profession, you can check the "**Buying this product requires approval**" in the settings of your product. If a customer tries to buy such a product, they will be able to place their order but can not proceed to payment. Instead, you will be asked to approve or deny the order and only if you approve it, we will send a payment link to the customer.
This requires the customer to interact with the ticket shop twice (once for the order, once for the payment) which adds a little more friction, but gives you full control over who attends the event.
Option C: Registered customers & memberships
""""""""""""""""""""""""""""""""""""""""""""
You can also do this by requiring that customers have a customer account and an active membership. You can find more
information on this mechanism in the :ref:`seasontickets` article.

92
doc/user/events/guides/season_tickets.rst
View File

@@ -1,92 +0,0 @@
.. _seasontickets:
Use case: Season tickets
========================
Season tickets and similar time-based tickets are popular for swimming pools, sports clubs, theaters and lots of other
types of venues. In this article, we show you different ways to set them up with pretix. Of course, other types of
tickets such as week tickets, month tickets or tickets of ten can be created with the same mechanism.
There is a big difference between the two ways we show below.
With **Option A**, a customer who purchases a season ticket creates an account with their email address and a password
and the season ticket will be saved in that account. If the customer wants to use the season ticket, they need to buy
an additional free ticket for the specific event they want to visit. This makes sense for all events or venues with
**limited capacity** or **reserved seating**, because it still allows you to set an upper limit of people showing up
for a specific event or time slot.
With **Option B**, a customer who purchases a season ticket receives a single ticket with a single QR code that can be
used an unlimited number of times. This makes sense if the capacity of your venue is virtually unlimited and you do not
need to know in advance how many season ticket holders will show up.
Option A: Memberships and multiple tickets
""""""""""""""""""""""""""""""""""""""""""
Since this approach requires customers to be identified with a customer account, you first need to enable the customer
accounts feature in your organizer settings in the "Customer accounts" tab.
.. thumbnail:: ../../../screens/event/seasontickets_orgsettings.png
:align: center
:class: screenshot
After doing so, a new menu item "Customer accounts" will also show up in the main menu of your organizer account on
the left. Open it's menu and click on "Membership types". Then, select to "create a new membership type".
You can name the membership type in a way that clearly explains where it is valid, e.g. "season pass main location"
or "season pass all locations". There are a few details you can configure on this page, such as whether the season pass
can be used by multiple different persons, or if the season pass can be used for multiple tickets for the same time
slot. You can also define a maximum number of usages, which is useful if you e.g. use this feature to add a "ticket of
ten".
.. thumbnail:: ../../../screens/event/seasontickets_membershiptype.png
:align: center
:class: screenshot
Next, you need a way of selling these season passes. Theoretically this can be done through the same event series that
you usually use, but it's probably cleaner and easier to find for customers if you create a **new event** that you only
use to sell season passes. The start and end date of the new event should correspond to the dates of your season.
Inside the new event, you only need to create a single product which you can call "season ticket". Inside that product's
settings, head to the "Additional settings" section and look for the option "This product creates a membership of type".
Select the membership type you just created. By default, the checkbox "The duration of the membership is the same as the
duration of the event or event series date" is active, which is fine for our season ticket example, but you might need
to unset it and provide custom timing for other ticket types such as week passes.
.. thumbnail:: ../../../screens/event/seasontickets_issue.png
:align: center
:class: screenshot
To prevent confusion, it might be useful to turn off ticket downloading at "Settings" → "Tickets" for your new event.
That's it, you are now ready to sell season tickets!
We can now deal with how to use the season tickets. Move back to your existing event and create a new product
**or** product variation of your regular product which you call "ticket for season ticket holders" and assign a price
of zero. In the "Availability" section of the product or variation settings, check the option "Require a valid
membership" and again select the membership type you created. You can of course repeat this with all events the season
ticket holder should have access to.
.. thumbnail:: ../../../screens/event/seasontickets_require.png
:align: center
:class: screenshot
Option B: All-access in a single pass
"""""""""""""""""""""""""""""""""""""
If you have only a single event series with many time slots and you do not care how many season ticket holders show up,
there's a solution that does not require your customers to set up accounts and book a new ticket on every visit.
Instead, you can just create an additional product "Season ticket" that you enable either in a "special" date of your
event series just created for this purpose, or in all of your dates so it can be easily found by customers.
Then, you can set up your check-in lists with custom logic in the "Advanced" tab of your check-in list settings.
The logic needs to ensure the following requirements:
* Regular ticket holders can only get in during their assigned time frame **and** when they haven't used their ticket before.
* Season ticket holders can always get in.
Here's an example on how to set this up:
.. thumbnail:: ../../../screens/event/seasontickets_rules.png
:align: center
:class: screenshot

24
doc/user/events/guides/terminology.rst
View File

@@ -1,24 +0,0 @@
Terminology
-----------
Products
A product is a basic entity that can be bought. You can think of it as a ticket type, but it can be more things than just a ticket, it can also be a piece of merchandise, a parking slot, etc.
You might find some places where they are called "items" instead, but we're trying to get rid of that.
Product categories
Products can be sorted into categories. Each product can only be in one category. Category are mostly used for grouping related products together to make your event page easier to read for buyers. However, we'll need categories as well to set up some of the structures outlined below.
Product variations
During creation of a product, you can decide that your product should have multiple variations. Variations of a product can differ in price, description, and availability, but are otherwise the same. You could use this e.g. for differentiating between a regular ticket and a discounted ticket for students, or when selling merchandise to differentiate the different sizes of a t-shirt.
Product add-ons
Add-ons are products that are sold together with another product (which we will call the base product in this case). For example, you could have a base product "Conference ticket" and then define multiple workshops that can be chosen as an add-on.
Product bundles
Bundles work very similarly to add-ons, but are different in the way that they are always automatically included with the base product and cannot be optional. In contrast to add-on products, the same product can be included multiple times in a bundle.
Quotas
Quotas define the availability of products. A quota has a size (i.e. the number of products in the inventory) and is mapped to one or multiple products or variations.
Questions
Questions are user-defined form fields that buyers will need to fill out when purchasing a product.

94
doc/user/events/guides/timeslots.rst
View File

@@ -1,94 +0,0 @@
.. _timeslots:
Use case: Time slots
====================
A more advanced use case of pretix is using pretix for time-slot-based access to an area with a limited visitor
capacity, such as a museum or other attraction. This guide will show you the quickest way to set up such an event
with pretix.
First of all, when creating your event, you need to select that your event represents an "event series":
.. thumbnail:: ../../../screens/event/create_step1.png
:align: center
:class: screenshot
You can click :ref:`here <subevents>` for a more general description of event series with pretix, but everything you
need to know is in this chapter as well.
General event setup
-------------------
Before you go further, set up your products that you want to sell for each time slot, such as different types of entry.
Creating slots
--------------
To create the time slots, you need to create a number of "dates" in the event series. Select "Dates" in the navigation
menu on the left side and click "Create many new dates". Then, first enter the pattern of your opening days. In the
example, the museum is open week Tuesday to Sunday. We recommend to create the slots for a few weeks at a time, but not
e.g. for a full year, since it will be more complicated to change things later.
.. thumbnail:: ../../../screens/event/timeslots_create.png
:align: center
:class: screenshot
Then, scroll to the times section and create your time slots. You can do any interval you like. If you have different
opening times on different week days, you will need to go through the creation process multiple times.
.. thumbnail:: ../../../screens/event/timeslots_create_2.png
:align: center
:class: screenshot
Scroll further down and create one or multiple quotas that define how many people can book a ticket for that time slot.
In this example, 50 people in total are allowed to enter within every slot:
.. thumbnail:: ../../../screens/event/timeslots_create_3.png
:align: center
:class: screenshot
Do **not** create a check-in list at this point. We will deal with this further below in the guide.
Now, press "Save" to create your slots.
.. warning:: If you create a lot of time slots at once, the server might need a few minutes to create them all in our
system. If you receive an error page because it took too long, please do not try again immediately but wait
for a few minutes. Most likely, the slots will be created successfully even though you saw an error.
Event settings
--------------
We recommend that you navigate to "Settings" > "General" > "Display" and set the settings "Default overview style"
to "Week calendar":
.. thumbnail:: ../../../screens/event/timeslots_settings_1.png
:align: center
:class: screenshot
Now, your ticket shop should give users a nice weekly overview over all time slots and their availability:
.. thumbnail:: ../../../screens/event/timeslots_presale.png
:align: center
:class: screenshot
Check-in
--------
If you want to scan people at the entrance of your event and only admit them at their designated time, we recommend
the following setup: Go to "Check-in" in the main navigation on the left and create a new check-in list. Give it a name
and do *not* choose a specific data. We will use one check-in list for all dates. Then, go to the "Advanced" tab at
the top and set up two restrictions to make sure people can only get in during the time slot they registered for.
You can create the rules exactly like shown in the following screenshot:
.. thumbnail:: ../../../screens/event/timeslots_checkinlists.png
:align: center
:class: screenshot
If you want, you can enter a tolerance of e.g. "10" if you want to be a little bit more relaxed and admit people up to
10 minutes before or after their time slot.
Now, download our `Android or Desktop app`_ and register it to your account. The app will ask you to select one the
time slots, but it does not matter, you can select any one of them and then select your newly created check-in list.
That's it, you're good to go!
.. _Android or Desktop app: https://pretix.eu/about/en/scan

17
doc/user/events/guides/upselling.rst
View File

@@ -1,17 +0,0 @@
Use case: Up-selling of ticket extras
-------------------------------------
Let's assume you're putting up a great music festival, and to save trouble with handling payments on-site, you want to sell parking spaces together with your ticket. By using our add-on feature, you can prompt all users to book the parking space (to make sure they see it) and ensure that only people with a ticket can book a parking space. You can set it up like this:
* Create a base product "Festival admission"
* Create a quota for the base product
* Create a category "Ticket extras" and check "Products in this category are add-on products"
* Create a product "Parking space" within that category
* Create a quota for the parking space product
* Go to the base product and select the tab "Add-Ons" at the top. Click "Add a new add-on" and choose the "Ticket extras" category. You can keep the numbers at 0 and 1.
During checkout, all buyers of the base product will now be prompted if they want to add the parking space.
.. tip::
You can also use add-on products for free things, just to keep tabs on capacity.

77
doc/user/events/guides/workshops.rst
View File

@@ -1,77 +0,0 @@
Use case: Conference with workshops
-----------------------------------
When running a conference, you might also organize a number of workshops with smaller capacity. To be able to plan, it would be great to know which workshops an attendee plans to attend.
Option A: Questions
"""""""""""""""""""
Your first and simplest option is to just create a multiple-choice question. This has the upside of making it easy for users to change their mind later on, but will not allow you to restrict the number of attendees signing up for a given workshop – or even charge extra for a given workshop.
Option B: Add-on products with fixed time slots
"""""""""""""""""""""""""""""""""""""""""""""""
The usually better option is to go with add-on products. Let's take for example the following conference schedule, in which the lecture can be attended by anyone, but the workshops only have space for 20 persons each:
==================== =================================== ===================================
Time Room A Room B
==================== =================================== ===================================
Wednesday morning Lecture
Wednesday afternoon Workshop A Workshop B
Thursday morning Workshop C Workshop D (20 € extra charge)
==================== =================================== ===================================
Assuming you already created one or more products for your general conference admission, we suggest that you additionally create:
* A category called "Workshops" with the checkbox "Products in this category are add-on products" activated
* A free product called "Wednesday afternoon" within the category "Workshops" and with two variations:
* Workshop A
* Workshop B
* A free product called "Thursday morning" within the category "Workshops" and with two variations:
* Workshop C
* Workshop D with a price of 20 €
* Four quotas for each of the workshops
* One add-on configuration on your base product that allows users to choose between 0 and 2 products from the category "Workshops"
Option C: Add-on products with variable time slots
""""""""""""""""""""""""""""""""""""""""""""""""""
The above option only works if your conference uses fixed time slots and every workshop uses exactly one time slot. If
your schedule looks like this, it's not going to work great:
+-------------+------------+-----------+
| Time | Room A | Room B |
+=============+============+===========+
| 09:00-11:00 | Talk 1 | Long |
+-------------+------------+ Workshop 1|
| 11:00-13:00 | Talk 2 | |
+-------------+------------+-----------+
| 14:00-16:00 | Long | Talk 3 |
+-------------+ workshop 2 +-----------+
| 16:00-18:00 | | Talk 4 |
+-------------+------------+-----------+
In this case, we recommend that you go to *Settings*, then *Plugins* and activate the plugin **Agenda constraints**.
Then, create a product (without variations) for every single part that should be bookable (talks 1-4 and long workshops
1 and 2) as well as appropriate quotas for each of them.
All of these products should be part of the same category. In your base product (e.g. your conference ticket), you
can then create an add-on product configuration allowing users to add products from this category.
If you edit these products, you will be able to enter the "Start date" and "End date" of the talk or workshop close
to the bottom of the page. If you fill in these values, pretix will automatically ensure no overlapping talks are
booked.
.. note::
This option is currently only available on pretix Hosted. If you are interested in using it with pretix Enterprise,
please contact sales@pretix.eu.

BIN
doc/user/events/img/widget_checkbox_button.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.0 KiB

116
doc/user/events/invoicing.rst
View File

@@ -1,116 +0,0 @@
Invoice settings
================
.. spelling:word-list:: Inv
The settings at "Settings" → "Invoice" allow you to specify if and how pretix should generate invoices for your orders.
.. thumbnail:: ../../screens/event/settings_invoice.png
:align: center
:class: screenshot
In particular, you can configure the following things:
Generate invoices
This field controls whether pretix should generate an invoice for an order. You have the following options:
No
pretix will never generate an invoice. If you want to issue invoices, you need to do it yourself based on the
collected address data.
Manually in admin panel
pretix will not create invoices automatically, but the order detail view will show a button that allows you to
manually generate one for specific orders.
Automatically on user request
pretix will not create invoices on its own, but both the panel as well as the customer view of the order will
show a button that instantly generates an invoice for the specified order.
Automatically for all created orders
pretix will automatically create an invoice every time an order is placed.
Automatically on payment
pretix will automatically create an invoice for an order, as soon as the payment for the order is received.
pretix will never generate invoices for free orders, even though it might ask for the invoice address.
Attach invoices to emails
If enabled, invoices will be attached to order confirmation e-mails if the "Generate invoices" setting is set to
"Automatically for all created orders" or to the payment confirmation e-mails if it is set to "Automatically on
payment".
Invoice number prefix
This is the prefix that will be prepended to all your invoice numbers. For example, if you set this to "Inv", your
invoices will be numbered Inv00001, Inv00002, etc. If you leave this field empty, your event slug will be used,
followed by a dash, e.g. DEMOCON-00001.
Within one organizer account, events with the same number prefix will share their number range. For example, if you
set this to "Inv" for all of your events, there will be only one invoice numbered Inv00007 across all your events
and the numbers will have gaps within one event.
Generate invoices with consecutive numbers
If enabled, invoices will be created with numerical invoice numbers in the order of their creation, i.e.
PREFIX-00001, PREFIX-00002, and so on. If disabled, invoice numbers will instead be generated from the order code,
i.e. PREFIX-YHASD-1. When in doubt, keep this option enabled since it might be legally required in your country,
but disabling it has the advantage that your customers can not estimate the number of tickets sold by looking at
the invoice numbers.
Invoice language
This setting allows you to configure the language of all invoices. You can either set it to one of your event
language or dynamically to the language used by the customer.
Show free products on invoices
If enabled, products that do not cost anything will still show up on invoices. Note that the order needs to contain
at least one non-free product in order to generate an invoice.
Show attendee names on invoices
If enabled, the attendee name will be printed on the invoice for admission tickets.
Ask for invoice address
If this checkbox is enabled, customers will be able to enter an invoice address during checkout. If you only enable
this box, the invoice address will be optional to fill in.
Require invoice address
If this checkbox is enabled, entering an invoice address will be obligatory for all customers and it will not be
able to create an order without entering an address.
Require customer name
If this checkbox is enabled, the street, city, and country fields of the invoice address will still be optional but
the name field will be obligatory.
Require a business address
If enabled, the invoice address form will require a company name and do not allow personal addresses.
Ask for beneficiary
If enabled, the invoice address form will contain an additional field to input the beneficiary of the transaction.
Ask for VAT ID
If enabled, the invoice address form will not only ask for a postal address, but also for a VAT ID. The VAT ID will
always be an optional field.
Generate invoices with consecutive numbers
If enabled, invoices will be created with numerical invoice numbers in the order of their creation, i.e.
PREFIX-00001, PREFIX-00002, and so on. If disabled, invoice numbers will instead be generated from the order code,
i.e. PREFIX-YHASD-1. When in doubt, keep this option enabled since it might be legally required in your country,
but disabling it has the advantage that your customers can not estimate the number of tickets sold by looking at
the invoice numbers.
Your invoice details
These fields should be set to the address of the entity issuing the invoice (read: you) and will be printed inside
the header of the invoice.
Invoice style
This setting allows you to choose the design of your invoice. Additional designs can be added by pretix plugins.
Introductory text
A free custom text that will be printed above the list of products on the invoice.
Additional text
A free custom text that will be printed below the list of products and the invoice total.
Footer
A text that will be printed in the foot line of the invoice. This could contain your contact details or legal
information on the issuing entity, e.g. registration numbers, your VAT ID, etc.
Logo image
A square image that will be printed in the invoice header, currently with a width of 2.5cm.

20
doc/user/events/plugins.rst
View File

@@ -1,20 +0,0 @@
Configuring plugins
===================
Plugins are optional parts of pretix that can be installed to extend the available functionality and that can be turned
on or off completely for every event. For your event, a number of plugins might be active already, but you can unlock
even more functionality by going to "Settings" → "Plugins" and enable more of them, if you need.
.. thumbnail:: ../../screens/event/settings_plugins.png
:align: center
:class: screenshot
For each plugin, you will find a short description as well as an Enable/Disable button. The pretix website has
`an overview`_ of available plugins and more details of them. If you are on the pretix.eu hosted service, look for
the "pretix Hosted" badge in the plugin list to learn which ones are supported there.
If you are running pretix on your own server, refer to the installation manual of your installation type to learn
how to install additional plugins (:ref:`manual <manual_plugininstall>` or :ref:`Docker <docker_plugininstall>`).
.. _an overview: https://pretix.eu/about/en/plugins

14
doc/user/events/settings.rst
View File

@@ -1,14 +0,0 @@
Configuring an event
====================
.. toctree::
:maxdepth: 2
subevents
../payments/index
plugins
display
tickets
email
taxes
invoicing

23
doc/user/events/structureguide.rst
View File

@@ -1,23 +0,0 @@
Product structure guide
=======================
Between products, categories, variations, add-ons, bundles, and quotas, pretix provides a wide range of features that allow you to set up your event in the way you want it.
However, it is easy to get lost in the process or to get started with building your event right.
Often times, there are multiple ways to do something that come with different advantages and disadvantages.
This guide will walk you through a number of typical examples of pretix event structures and will explain how to set them up – feel free to just skip ahead to a section relevant for you.
.. toctree::
:maxdepth: 1
guides/terminology
guides/pricelevels
guides/earlybird_dates
guides/earlybird_numbers
guides/upselling
guides/workshops
guides/packages
guides/groups
guides/restricted_audience
guides/timeslots
guides/season_tickets
guides/mixed_taxation

111
doc/user/events/subevents.rst
View File

@@ -1,111 +0,0 @@
.. _subevents:
Event series
============
During creation of a new event, you can choose that you want to create this event as an event series.
By event series, we mean a group of events that are similar in their structure and that you want to
sell within a single shop. An event series consists of **dates**. Each date represents one "event"
within the series.
For example, we think good examples to use the event series feature are:
* A theater or theater group that shows the same play on five evenings.
* A band on tour that hosts the same show in different locations.
* A workshop that is given multiple times in different locations or at different times.
We **don't** think that the feature is well-suited for events like the following:
* Event series distributed over a large timescale like annual conferences. We suggest using multiple events in this
case. You can avoid having to configure everything twice since you can copy settings from an existing event during
creation of the new event.
* Multiple parts of a conference or festival (e.g. different days) if a significant number of attendees will visit
more than one of them. We suggest just using different products in this case.
When using an event series, the single dates of the series are using the same settings in most places. They can
**only** differ in the following aspects:
* They can have different date, time, and location parameters.
* They can use different text on the shop front page.
* They can have different prices for the various products.
* They always have distinct quotas, which allows you to assign different amounts of tickets or to enable or disable
some products completely.
* They can have different rules for check-in.
Therefore, if your events are likely to need more different settings, this is probably not the feature for you. The
benefits of using event series, on the other hand, are:
* You only need to set most settings once, as the multiple dates live in the same shop.
* Your customers can build mixed orders, i.e. they can order tickets for multiple dates at once.
Creating and modifying dates in the series
------------------------------------------
Click on "Dates" in the left navigation menu of your event. This page shows you the list of currently existing event
dates and allows you to create, edit, clone and delete them.
If "Dates" is missing from the navigation menu, you have insufficient permission or your event has not been set up as
an event series and you need to create a new event.
.. thumbnail:: ../../screens/event/subevent_list.png
:align: center
:class: screenshot
If you click on one of them or create a new one, you will see the following form:
.. thumbnail:: ../../screens/event/subevent_create.png
:align: center
:class: screenshot
Here, you can make changes to the following fields, most of which are optional:
Name
This is the public name of your date. It should be descriptive enough to tell the user which date to select in
a calendar.
Active
This date will only show up for customers if you check this box. In this sense, it corresponds to the "live" setting
of events.
Event start time
The date and time that this date starts at.
Event end time
The date and time this date ends at.
Location
This is the location of your date in a human-readable format. We will show this on the ticket shop frontpage, but
it might also be used e.g. in Wallet tickets.
Admission time
The admission date and time to show on the ticket shop page or on the tickets.
Frontpage text
A text to show on the front page of the ticket shop for this date.
Start of presale
If you set this, no ticket will be sold before the time you set. If you set this on event series level as well,
both dates must be in the past for the tickets to be available.
End of presale
If you set this, no ticket will be sold after the time you set. If you set this on event series level as well,
both dates must be in the future for the tickets to be available.
Quotas
As for all events, no tickets will be available unless there is a quota created for them that specifies the number
of tickets available. You can create multiple quotas that are assigned to this date directly from this interface.
Item prices
This is a table of all products configured for your shop. If you want, you can enter a new price for each one of them
in the right column to make them cheaper or more expensive for this date. If you leave a field empty, the price will
follow the product's default price.

121
doc/user/events/taxes.rst
View File

@@ -1,121 +0,0 @@
.. _taxes:
Configuring taxes
=================
In most countries, you will be required to pay some form of sales tax for your event tickets. If you don't know about
the exact rules, you should consult a professional tax consultant right now.
To implement those taxes in pretix, you can create one or multiple "tax rules". A tax rule specifies when and at what
rate should be calculated on a product price. Taxes will then be correctly displayed in the product list, order
details and on invoices.
At the time of this writing, every product can be assigned exactly one tax rule. To view and change the tax rules of
your event, go to the respective section in your event's settings:
.. thumbnail:: ../../screens/event/tax_list.png
:align: center
:class: screenshot
On this page, you can create, edit and delete your tax rules. Clicking on the name of a tax rule will take you to its
detailed settings:
.. thumbnail:: ../../screens/event/tax_detail.png
:align: center
:class: screenshot
Here, you can tune the following parameters:
Name
What is the (short) name of this tax? This is probably "VAT" in English and should be very short as it will be
displayed in lots of places.
Rate
This is the tax rate in percent.
The configured product prices include the tax amount
If this setting is enabled (the default), then a product configured to a price of 10.00 EUR will, at a tax rate of
19.00 %, be interpreted as a product with a total gross price of 10.00 EUR including 1.60 EUR taxes, leading to a
net price of 8.40 EUR. If you disable this setting, the price will be interpreted as a net price of 10.00 EUR,
leading to a total price to pay of 11.90 EUR.
Use EU reverse charge taxation rules
This enables reverse charge taxation (see section below).
Merchant country
This is probably your country of residence, but in some cases it could also be the country your event is
located in. This is the place of taxation in the sense of EU reverse charge rules (see section below).
EU reverse charge
-----------------
.. warning:: Everything contained in this section is not legal advice. Please consult a tax consultant
before making decisions. We are not responsible for the correct handling of taxes in your
ticket shop.
"Reverse charge" is a rule in European VAT legislation that specifies how taxes are paid
if you provide goods to a buyer in a different European country than you reside in yourself.
If the buyer is a VAT-paying business in their country, you charge them only the net price without
taxes and state that the buyer is responsible for paying the correct taxes themselves.
.. warning:: We firmly believe that reverse charge rules are **not applicable** for most events handled
with pretix and therefore **strongly recommend not to enable this feature** if you do not have
a specific reason to do so. The reasoning behind this is that according to article 52 of the
`VAT directive`_ (page 17), the place of supply is always the location of your event and
therefore the tax rate of the event country always has to be paid regardless of the location
of the visitor.
If you enable the reverse charge feature and specify your merchant country, then the following process
will be performed during order creation:
* The user will first be presented with the "normal" prices (net or gross, as configured).
* The user adds a product to their cart. The cart will at this point always show gross prices *with*
taxes.
* In the next step, the user can enter an invoice address. Tax will be removed from the price if one of the
following statements is true:
* The invoice address is in a non-EU country.
* The invoice address is a business address in an EU-country different from the merchant country and has a valid VAT ID.
* In the second case, a reverse charge note will be added to the invoice.
VAT IDs are validated against the EUs validation web service. Should that service be unavailable, the user
needs to pay VAT tax and reclaim the taxes at a later point in time with their government.
If you and the buyer are residing in EU countries that use different currencies, the invoice will show
the total and VAT amount also in the local currency of the buyer, if the system was able to obtain a
conversion rate from the European Central Bank's webservice within the last 7 days.
For existing orders, a change of the invoice address will not result in a change of taxes automatically.
You can trigger this manually in the backend by going to the order's detail view. There, first click
the "Check" button next to the VAT ID. Then, go to "Change products" and select the option "Recalculate
taxes" at the end of the page.
.. note:: In the invoicing settings, you should turn the setting "Ask for VAT ID" on for this to work.
.. note:: During back-and-forth modification of taxation status, unfortunately there can be rounding
errors of usually up to one cent from the intended price. This is unavoidable due to the
flexible nature in which prices are being calculated.
Custom tax rules
----------------
If you have very special requirements for the conditions in which VAT will or will not be charged, you can use the
"Custom tax rules" section instead of the options listed above. Here, you can create a set of rules consisting of
conditions (i.e. a country or a type of customer) and actions (i.e. do or do not charge VAT).
The rules will then be checked from top to bottom and the first matching rule will be used to decide if VAT will be
charged to the user.
Taxation of payment fees
------------------------
In the payment part of your event settings, you can choose the tax rule that needs to be applied for
payment method fees. This works in the same way as product prices, with the small difference that the
"configured product prices include the tax amount" settings is ignored and payment fees will always be
treated as gross values.
.. _VAT directive: http://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32006L0112&from=EN

96
doc/user/events/ticket_secrets.rst
View File

@@ -1,96 +0,0 @@
.. _secret_generators:
Ticket secret generators
========================
pretix allows you to change the way in which ticket secrets (also known as "ticket codes", "barcodes", …)
are generated. This affects the value of the QR code in any tickets issued by pretix, regardless of ticket
format.
.. note:: This is intended for highly advanced use cases, usually when huge numbers of tickets (> 25k per event)
are involved. **If you don't know whether you need this, you probably don't.**
Default: Random secrets
-----------------------
By default, pretix generates a random code for every ticket, consisting of 32 lower case characters and
numbers. The characters ``oO1il`` are avoided to reduce confusion when ticket codes are printed and need to
be typed in manually.
Choosing random codes has a number of advantages:
* Ticket codes are short, which makes QR codes easier to scan. At the same time, it is absolutely impossible to
guess or forge a valid ticket code.
* The code does not need to change if the ticket changes. For example, if an attendee is re-booked to a
different product or date, they can keep their ticket and it is just mapped to the new product in the
database.
This approach works really well for 99 % or events running with pretix.
The big caveat is that the scanner needs to access a database of all ticket codes in order to know whether a ticket
code is valid and what kind of ticket it represents.
When scanning online this is no problem at all, since the pretix server always has such a database. In case your local
internet connection is interrupted or the pretix server goes down, though, there needs to be a database locally on the
scanner.
Therefore, our pretixSCAN apps by default download the database of all valid tickets onto the device itself. This makes
it possible to seamlessly switch into offline mode when the connection is lost and continue scanning with the maximum
possible feature set.
There are a few situations in which this approach is not ideal:
* When running a single event with 25k or more valid tickets, downloading all ticket data onto the scanner may just
take too much time and resources.
* When the risk of losing sensible data by losing one of the scanner devices is not acceptable.
* When offline mode needs to be used regularly and newly-purchased tickets need to be valid immediately after purchase,
without being able to tolerate a few minutes of delay.
Signature schemes
-----------------
The alternative approach that is included with pretix is to choose a signature-based ticket code generation scheme.
These secrets include the most important information that is required for verifying their validity and use modern
cryptography to make sure they cannot be forged.
Currently, pretix ships with one such scheme ("pretix signature scheme 1") which encodes the product, the product
variation, and the date (if inside an event series) into the ticket code and signs the code with a `EdDSA`_ signature.
This allows to verify whether a ticket is allowed to enter without any database or connection to the server, but has
a few important drawbacks:
* Whenever the product, variation or date of a ticket changes or the ticket is canceled, the ticket code needs to be
changed and the old code needs to be put on a revocation list. This revocation list again needs to be downloaded by
all scanning devices (but is usually much smaller than the ticket database). The main downside is that the attendee
needs to download their new ticket and can no longer use the old one.
* Scanning in offline mode is much more limited, since the scanner has no information about previous usages of the
ticket, attendee names, seating information, etc.
Comparison of scanning behavior
-------------------------------
=============================================== =================================== =================================== =================================== ================================= =====================================
Scan mode Online Offline
----------------------------------------------- ----------------------------------- -----------------------------------------------------------------------------------------------------------------------------------------------
Synchronization setting any Synchronize orders Don't synchronize orders
----------------------------------------------- ----------------------------------- ----------------------------------------------------------------------- -----------------------------------------------------------------------
Ticket secrets any Random Signed Random Signed
=============================================== =================================== =================================== =================================== ================================= =====================================
Scenario supported on platforms Android, Desktop, iOS Android, Desktop, iOS Android, Desktop Android, Desktop, iOS Android, Desktop, iOS
Synchronization speed for large data sets slow slow fast fast
Tickets can be scanned yes yes yes no yes
Ticket is valid after sale immediately next sync (~5 minutes) immediately never immediately
Same ticket can be scanned multiple times no yes, before data is synced yes, before data is synced n/a yes, always
Custom check-in rules yes yes yes (limited directly after sale) n/a yes, but only based on product,
variation and date, not on previous
scans
Name and seat visible on scanner yes yes yes (except directly after sale) n/a no
Order-specific check-in attention flag yes yes yes (except directly after sale) n/a no
Ticket search by order code or name yes yes yes (except directly after sale) no no
Check-in statistics on scanner yes yes mostly accurate no no
Support for add-on check-in with main ticket yes yes yes (except directly after sale) no no
=============================================== =================================== =================================== =================================== ================================= =====================================
.. _EdDSA: https://en.wikipedia.org/wiki/EdDSA#Ed25519

41
doc/user/events/tickets.rst
View File

@@ -1,41 +0,0 @@
Ticket settings
===============
At "Settings" → "Tickets", you can configure the ticket download options that will be presented to your customers:
.. thumbnail:: ../../screens/event/settings_tickets.png
:align: center
:class: screenshot
The top of this page shows a short list of options relevant for all download formats:
Allow users to download tickets
This can be used to completely enable or disable ticket downloads all over your ticket shop.
Generate tickets for add-on products
By default, tickets can not be downloaded for order positions which are only an add-on to other order positions. If
you enable this, this behavior will be changed and add-on products will get their own tickets as well. If disabled,
you can still print a list of chosen add-ons e.g. on the PDF tickets.
Generate tickets for all products
By default, tickets will only be generated for products that are marked as admission products. Enable this option to
generate tickets for all products instead.
Generate tickets for pending orders
By default, ticket download is only possible for paid orders. If you run an event where people usually pay only after
the event, you can check this box to enable ticket download even before.
Download date
If you set a date here, no ticket download will be offered before this date. If no date is set, tickets can be
downloaded immediately after the payment for an order has been received.
Below these settings, the detail settings for the various ticket file formats are offered. They differ from format to
format and only share the common "Enable" setting that can be used to turn them on. By default, pretix ships with
a PDF output plugin that you can configure through a visual design editor.
**Advanced topics:**
.. toctree::
:maxdepth: 1
ticket_secrets

497
doc/user/events/widget.rst
View File

@@ -1,497 +0,0 @@
.. _widget:
Embeddable Widget
=================
If you want to show your ticket shop on your event website or blog, you can use our JavaScript widget. This way,
users will not need to leave your site to buy their ticket in most cases.
To obtain the correct HTML code for embedding your event into your website, we recommend that you go to the "Widget"
tab of your event's settings. You can specify some optional settings there (for example the language of the widget)
and then click "Generate widget code".
.. thumbnail:: ../../screens/event/widget_form.png
:align: center
:class: screenshot
You will obtain two code snippets that look *roughly* like the following. The first should be embedded into the
``<head>`` part of your website, if possible. If this inconvenient, you can put it in the ``<body>`` part as well::
<link rel="stylesheet" type="text/css" href="https://pretix.eu/demo/democon/widget/v1.css" crossorigin>
<script type="text/javascript" src="https://pretix.eu/widget/v1.en.js" async crossorigin></script>
The second snippet should be embedded at the position where the widget should show up::
<pretix-widget event="https://pretix.eu/demo/democon/"></pretix-widget>
<noscript>
<div class="pretix-widget">
<div class="pretix-widget-info-message">
JavaScript is disabled in your browser. To access our ticket shop without JavaScript,
please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
</div>
</div>
</noscript>
.. note::
You can of course embed multiple widgets of multiple events on your page. In this case, please add the first
snippet only *once* and the second snippets once *for each event*.
.. note::
Some website builders like Jimdo have trouble with our custom HTML tag. In that case, you can use
``<div class="pretix-widget-compat" …></div>`` instead of ``<pretix-widget …></pretix-widget>`` starting with
pretix 1.14.
Example
-------
Your embedded widget could look like the following:
.. raw:: html
<link rel="stylesheet" type="text/css" href="https://pretix.eu/demo/democon/widget/v1.css">
<script type="text/javascript" src="https://pretix.eu/widget/v1.en.js" async></script>
<pretix-widget event="https://pretix.eu/demo/democon/"></pretix-widget>
<noscript>
<div class="pretix-widget">
<div class="pretix-widget-info-message">
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
</div>
</div>
</noscript>
Styling
-------
If you want, you can customize the appearance of the widget to fit your website with CSS. If you inspect the rendered
HTML of the widget with your browser's developer tools, you will see that nearly every element has a custom class
and all classes are prefixed with ``pretix-widget``. You can override the styles as much as you want to and if
you want to go all custom, you don't even need to use the stylesheet provided by us at all.
SSL
---
Since buying a ticket normally involves entering sensitive data, we strongly suggest that you use SSL/HTTPS for the page
that includes the widget. Initiatives like `Let's Encrypt`_ allow you to obtain a SSL certificate free of charge.
All data transferred to pretix will be made over SSL, even if using the widget on a non-SSL site. However, without
using SSL for your site, a man-in-the-middle attacker could potentially alter the widget in dangerous ways. Moreover,
using SSL is becoming standard practice and your customers might want expect see the secure lock icon in their browser
granted to SSL-enabled web pages.
By default, the checkout process will open in a new tab in your customer's browsers if you don't use SSL for your
website. If you confident to have a good reason for not using SSL, you can override this behavior with the
``skip-ssl-check`` attribute::
<pretix-widget event="https://pretix.eu/demo/democon/" skip-ssl-check></pretix-widget>
Always open a new tab
---------------------
If you want the checkout process to always open a new tab regardless of screen size, you can pass the ``disable-iframe``
attribute::
<pretix-widget event="https://pretix.eu/demo/democon/" disable-iframe></pretix-widget>
Always show event’s info
------------------------
If you want the widget to show the event’s info such as title, location and frontpage text, you can pass the optional
``display-event-info`` attribute with either a value of ``"false"``, ``"true"`` or ``"auto"`` – the latter being the
default if the attribute is not present at all.
Note that any other value than ``"false"`` or ``"auto"`` means ``"true"``::
<pretix-widget event="https://pretix.eu/demo/democon/" display-event-info></pretix-widget>
Pre-selecting a voucher
-----------------------
You can pre-select a voucher for the widget with the ``voucher`` attribute::
<pretix-widget event="https://pretix.eu/demo/democon/" voucher="ABCDE123456"></pretix-widget>
This way, the widget will only show products that can be bought with the voucher and prices according to the
voucher's settings.
.. raw:: html
<pretix-widget event="https://pretix.eu/demo/democon/" voucher="ABCDE123456"></pretix-widget>
<noscript>
<div class="pretix-widget">
<div class="pretix-widget-info-message">
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
</div>
</div>
</noscript>
Disabling the voucher input
---------------------------
If you want to disable voucher input in the widget, you can pass the ``disable-vouchers`` attribute::
<pretix-widget event="https://pretix.eu/demo/democon/" disable-vouchers></pretix-widget>
Enabling the button-style single item select
--------------------------------------------
By default, the widget uses a checkbox to select items, that can only be bought in quantities of one. If you want to match
the button-style of that checkbox with the one in the pretix shop, you can use the ``single-item-select`` attribute::
<pretix-widget event="https://pretix.eu/demo/democon/" single-item-select="button"></pretix-widget>
.. image:: img/widget_checkbox_button.png
:align: center
:class: screenshot
.. note::
Due to compatibility with existing widget installations, the default value for ``single-item-select``
is ``checkbox``. This might change in the future, so make sure, to set the attribute to
``single-item-select="checkbox"`` if you need it.
Filtering products
------------------
You can filter the products shown in the widget by passing in a list of product IDs::
<pretix-widget event="https://pretix.eu/demo/democon/" items="23,42"></pretix-widget>
Alternatively, you can select one or more categories to be shown::
<pretix-widget event="https://pretix.eu/demo/democon/" categories="12,25"></pretix-widget>
Or variation IDs::
<pretix-widget event="https://pretix.eu/demo/democon/" variations="15,2,68"></pretix-widget>
Multi-event selection
---------------------
If you want to embed multiple events in a single widget, you can do so. If it's multiple dates of an event series, just leave off the ``series`` attribute::
<pretix-widget event="https://pretix.eu/demo/series/"></pretix-widget>
If you want to include all your public events, you can just reference your organizer::
<pretix-widget event="https://pretix.eu/demo/"></pretix-widget>
There is an optional ``style`` parameter that let's you choose between a monthly calendar view, a week view and a list
view. If you do not set it, the choice will be taken from your organizer settings::
<pretix-widget event="https://pretix.eu/demo/series/" list-type="list"></pretix-widget>
<pretix-widget event="https://pretix.eu/demo/series/" list-type="calendar"></pretix-widget>
<pretix-widget event="https://pretix.eu/demo/series/" list-type="week"></pretix-widget>
If you have more than 100 events, the system might refuse to show a list view and always show a calendar for performance
reasons instead.
You can see an example here:
.. raw:: html
<pretix-widget event="https://pretix.eu/demo/series/" list-type="calendar"></pretix-widget>
<noscript>
<div class="pretix-widget">
<div class="pretix-widget-info-message">
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/series/">click here</a>.
</div>
</div>
</noscript>
You can filter events by meta data attributes. You can create those attributes in your order profile and set their values in both event and series date
settings. For example, if you set up a meta data property called "Promoted" that you set to "Yes" on some events, you can pass a filter like this::
<pretix-widget event="https://pretix.eu/demo/series/" list-type="list" filter="attr[Promoted]=Yes"></pretix-widget>
If you have enabled public filters in your meta data attribute configuration, a filter-form shows up. To disable, use::
<pretix-widget event="https://pretix.eu/demo/democon/" disable-filters></pretix-widget>
pretix Button
-------------
Instead of a product list, you can also display just a single button. When pressed, the button will add a number of
products associated with the button to the cart and will immediately proceed to checkout if the operation succeeded.
You can try out this behavior here:
.. raw:: html
<pretix-button event="https://pretix.eu/demo/democon/" items="item_6424=1">Buy ticket!</pretix-button>
<noscript>
<div class="pretix-widget">
<div class="pretix-widget-info-message">
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
</div>
</div>
</noscript>
<br><br>
You can embed the pretix Button just like the pretix Widget. Just like above, first embed the CSS and JavaScript
resources. Then, instead of the ``pretix-widget`` tag, use the ``pretix-button`` tag::
<pretix-button event="https://pretix.eu/demo/democon/" items="item_6424=1">
Buy ticket!
</pretix-button>
As you can see, the ``pretix-button`` element takes an additional ``items`` attribute that specifies the items that
should be added to the cart. The syntax of this attribute is ``item_ITEMID=1,item_ITEMID=2,variation_ITEMID_VARID=4``
where ``ITEMID`` are the internal IDs of items to be added and ``VARID`` are the internal IDs of variations of those
items, if the items have variations. If you omit the ``items`` attribute, the general start page will be presented.
In case you are using an event-series, you will need to specify the subevent for which the item(s) should be put in the
cart. This can be done by specifying the ``subevent``-attribute.
Just as the widget, the button supports the optional attributes ``voucher``, ``disable-iframe``, and ``skip-ssl-check``.
You can style the button using the ``pretix-button`` CSS class.
Dynamically opening the widget
------------------------------
You can get the behavior of the pretix Button without a button at all, so you can trigger it from your own code in
response to a user action. Usually, this will open an overlay with your ticket shop, however in some cases, such as
missing HTTPS encryption on your case or a really small screen (mobile), it will open a new tab instead of an overlay.
Therefore, make sure you call this *in direct response to a user action*, otherwise most browser will block it as an
unwanted pop-up.
.. js:function:: window.PretixWidget.open(target_url [, voucher [, subevent [, items, [, widget_data [, skip_ssl_check ]]]]])
:param string target_url: The URL of the ticket shop.
:param string voucher: A voucher code to be pre-selected, or ``null``.
:param string subevent: A subevent to be pre-selected, or ``null``.
:param array items: A collection of items to be put in the cart, of the form ``[{"item": "item_3", "count": 1}, {"item": "variation_5_6", "count": 4}]``
:param object widget_data: Additional data to be passed to the shop, see below.
:param boolean skip_ssl_check: Whether to ignore the check for HTTPS. Only to be used during development.
Dynamically loading the widget
------------------------------
If you need to control the way or timing the widget loads, for example because you want to modify user data (see
below) dynamically via JavaScript, you can register a listener that we will call before creating the widget::
<script type="text/javascript">
window.pretixWidgetCallback = function () {
// Will be run before we create the widget.
}
</script>
If you want, you can suppress us loading the widget and/or modify the user data passed to the widget::
<script type="text/javascript">
window.pretixWidgetCallback = function () {
window.PretixWidget.build_widgets = false;
window.PretixWidget.widget_data["email"] = "test@example.org";
}
</script>
If you then later want to trigger loading the widgets, just call ``window.PretixWidget.buildWidgets()``.
Waiting for the widget to load or close
---------------------------------------
If you want to run custom JavaScript once the widget is fully loaded or when it is closed, you can register callback
functions. Note that these function might be run multiple times, for example if you have multiple widgets on a page
or if the user switches e.g. from an event list to an event detail view::
<script type="text/javascript">
window.pretixWidgetCallback = function () {
window.PretixWidget.addLoadListener(function () {
console.log("Widget has loaded!");
});
window.PretixWidget.addCloseListener(function () {
console.log("Widget has been closed!");
});
}
</script>
Passing user data to the widget
-------------------------------
If you display the widget in a restricted area of your website and you want to pre-fill fields in the checkout process
with known user data to save your users some typing and increase conversions, you can pass additional data attributes
with that information::
<pretix-widget event="https://pretix.eu/demo/democon/"
data-attendee-name-given-name="John"
data-attendee-name-family-name="Doe"
data-invoice-address-name-given-name="John"
data-invoice-address-name-family-name="Doe"
data-email="test@example.org"
data-question-L9G8NG9M="Foobar">
</pretix-widget>
This works for the pretix Button as well, if you also specify a product.
As data-attributes are reactive, you can change them with JavaScript as well. Please note, that once the user
started the checkout process, we do not update the data-attributes in the existing checkout process to not
interrupt the checkout UX.
When updating data-attributes through JavaScript, make sure you do not have a stale reference to the HTMLNode of the
widget. When the widget is created, the original HTMLNode can happen to be replaced. So make sure to always have a
fresh reference like so
``document.querySelectorAll("pretix-widget, pretix-button, .pretix-widget-wrapper")``
Currently, the following attributes are understood by pretix itself:
* ``data-email`` will pre-fill the order email field as well as the attendee email field (if enabled).
* ``data-question-IDENTIFIER`` will pre-fill the answer for the question with the given identifier. You can view and set
identifiers in the *Questions* section of the backend.
* Depending on the person name scheme configured in your event settings, you can pass one or more of
``data-attendee-name-full-name``, ``data-attendee-name-given-name``, ``data-attendee-name-family-name``,
``data-attendee-name-middle-name``, ``data-attendee-name-title``, ``data-attendee-name-calling-name``,
``data-attendee-name-latin-transcription``. If you don't know or don't care, you can also just pass a string as
``data-attendee-name``, which will pre-fill the last part of the name, whatever that is.
* ``data-invoice-address-FIELD`` will pre-fill the corresponding field of the invoice address. Possible values for
``FIELD`` are ``company``, ``street``, ``zipcode``, ``city``, ``country``, ``internal-reference``, ``vat-id``, and
``custom-field``, as well as fields specified by the naming scheme such as ``name-title`` or ``name-given-name``
(see above). ``country`` expects a two-character country code.
* If ``data-fix="true"`` is given, the user will not be able to change the other given values later. This currently
only works for the order email address as well as the invoice address. Attendee-level fields and questions can
always be modified. Note that this is not a security feature and can easily be overridden by users, so do not rely
on this for authentication.
* If ``data-consent="…"`` is given, the cookie consent mechanism will be initialized with consent for the given cookie
providers. All other providers will be disabled, no consent dialog will be shown. This is useful if you already
asked the user for consent and don't want them to be asked again. Example: ``data-consent="facebook,google_analytics"``
When using the pretix-tracking plugin, the following values are supported::
``adform, facebook, gosquared, google_ads, google_analytics, hubspot, linkedin, matomo, twitter``
Any configured pretix plugins might understand more data fields. For example, if the appropriate plugins on pretix
Hosted or pretix Enterprise are active, you can pass the following fields:
* If you use the campaigns plugin, you can pass a campaign ID as a value to ``data-campaign``. This way, all orders
made through this widget will be counted towards this campaign.
* If you use the tracking plugin, you can enable cross-domain tracking. Please note: when you run your pretix-shop on a
subdomain of your main tracking domain, then you do not need cross-domain tracking as tracking automatically works
across subdomains. See :ref:`custom_domain` for how to set this up.
Please make sure to add the embedding website to your `Referral exclusions
<https://support.google.com/analytics/answer/2795830>`_ in your Google Analytics settings.
Add Google Analytics as you normally would with all your `window.dataLayer` and `gtag` configurations. Also add the
widget code normally. Then you have two options:
* Block loading of the widget at most 2 seconds or until Google’s client- and session-ID are loaded. This method
uses `window.pretixWidgetCallback`. Note that if it takes longer than 2 seconds to load, client- and session-ID
are never passed to the widget. Make sure to replace all occurrences of <MEASUREMENT_ID> with your Google
Analytics MEASUREMENT_ID (G-XXXXXXXX)::
<script type="text/javascript">
window.pretixWidgetCallback = function () {
window.PretixWidget.build_widgets = false;
window.addEventListener('load', function() { // Wait for GA to be loaded
if (!window['google_tag_manager']) {
window.PretixWidget.buildWidgets();
return;
}
var clientId;
var sessionId;
var loadingTimeout;
function build() {
// use loadingTimeout to make sure build() is only called once
if (!loadingTimeout) return;
window.clearTimeout(loadingTimeout);
loadingTimeout = null;
if (clientId) window.PretixWidget.widget_data["tracking-ga-id"] = clientId;
if (sessionId) window.PretixWidget.widget_data["tracking-ga-sessid"] = sessionId;
window.PretixWidget.buildWidgets();
};
// make sure to build pretix-widgets if gtag fails to load either client_id or session_id
loadingTimeout = window.setTimeout(build, 2000);
gtag('get', '<MEASUREMENT_ID>', 'client_id', function(id) {
clientId = id;
if (sessionId !== undefined) build();
});
gtag('get', '<MEASUREMENT_ID>', 'session_id', function(id) {
sessionId = id;
if (clientId !== undefined) build();
});
});
};
</script>
* Or asynchronously set data-attributes – the widgets are shown immediately, but once the user has started checkout,
data-attributes are not updated. Make sure to replace all occurrences of <MEASUREMENT_ID> with your Google
Analytics MEASUREMENT_ID (G-XXXXXXXX)::
<script type="text/javascript">
window.addEventListener('load', function() {
gtag('get', '<MEASUREMENT_ID>', 'client_id', function(id) {
const widgets = document.querySelectorAll("pretix-widget, pretix-button, .pretix-widget-wrapper");
widgets.forEach(widget => widget.setAttribute("data-tracking-ga-id", id))
});
gtag('get', '<MEASUREMENT_ID>', 'session_id', function(id) {
const widgets = document.querySelectorAll("pretix-widget, pretix-button, .pretix-widget-wrapper");
widgets.forEach(widget => widget.setAttribute("data-tracking-ga-sessid", id))
});
});
</script>
Offering wallet payments (Apple Pay, Google Pay) within the widget
------------------------------------------------------------------
Some payment providers (such as Stripe) also offer Apple or Google Pay. But in order to use them, the domain of the
payment needs to be approved first. As of right now, pretix will take care of the domain verification process for you
automatically, when using Stripe. However, pretix can only validate the domain that is being used for your default,
"stand-alone" shop (such as https://pretix.eu/demo/democon/ ).
When embedding the widget on your website, the domain of the embedding page will also need to be validated in order to
be able to use it for wallet payments.
The details might vary from payment provider to payment provider, but generally speaking, it will either involve just
telling your payment provider the domain name and (for Apple Pay) placing an
``apple-developer-merchantid-domain-association``-file into the ``.well-known``-directory of your domain.
Further reading:
* `Stripe Payment Method Domain registration`_
Content Security Policy
-----------------------
When using a Content Security Policy (CSP) on your website, you may need to make some adjustments. If your pretix
shop is running under a custom domain, you need to add the following rules:
* ``script-src``: ``'unsafe-eval' https://pretix.eu`` (adjust to your domain for self-hosted pretix)
* ``style-src``: ``https://pretix.eu`` (adjust to your domain for self-hosted pretix **and** for custom domain on pretix Hosted)
* ``connect-src``: ``https://pretix.eu`` (adjust to your domain for self-hosted pretix **and** for custom domain on pretix Hosted)
* ``frame-src``: ``https://pretix.eu`` (adjust to your domain for self-hosted pretix **and** for custom domain on pretix Hosted)
* ``img-src``: ``https://pretix.eu`` (adjust to your domain for self-hosted pretix **and** for custom domain on pretix Hosted) and for pretix Hosted additionally add ``https://cdn.pretix.space``
External payment providers and Cross-Origin-Opener-Policy
---------------------------------------------------------
If you use a payment provider that opens a new window during checkout (such as PayPal), be aware that setting
``Cross-Origin-Opener-Policy: same-origin`` results in an empty popup-window being opened in the foreground. This is
due to JavaScript not having access to the opened window. To mitigate this, you either need to always open the widget’s
checkout in a new tab (see :ref:`Always open a new tab`) or set ``Cross-Origin-Opener-Policy: same-origin-allow-popups``
Working with Cross-Origin-Embedder-Policy
-----------------------------------------
The pretix widget is unfortunately not compatible with ``Cross-Origin-Embedder-Policy: require-corp``. If you include
the ``crossorigin`` attributes on the ``<script>`` and ``<link>`` tag as shown above, the widget can show a calendar
or product list, but will not be able to open the checkout process in an iframe. If you also set
``Cross-Origin-Opener-Policy: same-origin``, the widget can auto-detect that it is running in an isolated enviroment
and will instead open the checkout process in a new tab.
.. _Let's Encrypt: https://letsencrypt.org/
.. _Stripe Payment Method Domain registration: https://stripe.com/docs/payments/payment-methods/pmd-registration

106
doc/user/faq.rst
View File

File diff suppressed because one or more lines are too long

193
doc/user/glossary.rst
View File

@@ -1,193 +0,0 @@
Glossary
========
This page gives definitions of domain-specific terms that we use a lot inside pretix and that might be used slightly
differently elsewhere, as well as their official translations to other languages. In some cases, things have a different
name internally, which is noted with a |:wrench:| symbol. If you only use pretix, you'll never see these, but if you're
going to develop around pretix, for example connect to pretix through our API, you need to know these as well.
.. rst-class:: rest-resource-table
.. list-table:: Glossary
:widths: 15 30
:header-rows: 1
* - Term
- Definition
* - | |:gb:| **Organizer**
| |:de:| Veranstalter
- An organizer represents the entity using pretix, usually the company or institution running one or multiple events.
In terms of navigation in the system, organizers are the "middle layer" between the system itself and the specific
events.
Multiple organizers on the same pretix system are fully separated from each other with very few exceptions.
* - | |:gb:| **Event**
| |:de:| Veranstaltung
- An event is the central entity in pretix that you and your customers interact with all the time. An event
represents one **shop** in which things like tickets can be bought. Since the introduction of event series (see
below), this might include multiple events in the real world.
Every purchase needs to be connected to an event, and most things are completely separate between different
events, i.e. most actions and configurations in pretix are done per-event.
* - | |:gb:| **Event series**
| |:de:| Veranstaltungsreihe
- An event series is one of two types of events. Unlike a non-series event, an event series groups together
multiple real-world events into one pretix shop. Examples are time-slot-based booking for a museum, a band on
tour, a theater group playing the same play multiple times, etc.
* - | |:gb:| **Date**
| |:de:| Termin
| |:wrench:| Subevent
- A date represents a single real-world event inside an event series. Dates can differ from each other in name,
date, time, location, pricing, capacity, and seating plans, but otherwise share the same configuration.
* - | |:gb:| **Product**
| |:de:| Produkt
| |:wrench:| Item
- A product is anything that can be sold, such as a specific type of ticket or merchandise.
* - | |:gb:| **Admission product**
| |:de:| Zutrittsprodukt
- A product is considered an **admission product** if its purchase represents a person being granted access to your
event. This applies to most ticketing products, but not e.g. to merchandise.
* - | |:gb:| **Variation**
| |:de:| Variante
| |:wrench:| Item variation
- Some products come in multiple variations that can differ in description, price and capacity. Examples would
include "Adult" and "Child" in case of a concert ticket, or "S", "M", "L", … in case of a t-shirt product.
* - | |:gb:| **Category**
| |:de:| Kategorie
- Products can be grouped together in categories. This is mostly to organize them cleanly in the frontend if you
have lots of them.
* - | |:gb:| **Quota**
| |:de:| Kontingent
- A quota is a capacity pool that defines how many times a product can be sold. A quota can be connected to multiple
products, in which case all of them are counted together. This is useful e.g. if you have full-price and reduced
tickets and only want to sell a certain number of tickets in total. The same way, multiple quotas can be connected
to the same product, in which case the ticket will be available as long as all of them have capacity left.
* - | |:gb:| **Add-on product**
| |:de:| Zusatzprodukt
- An add-on product is a product that is purchased as an upgrade or optional addition to a different product.
Examples would be include a conference ticket that optionally allows to buy a public transport ticket for the
same day, or a family ticket for 4 persons that allows you to add additional persons at a small cost, or a
"two workshops" package that allows you to select two of a larger number of workshops at a discounted price.
In all cases, there is a "main product" (the conference ticket, the family ticket) and a number of "add-on products"
that can be chosen from.
* - | |:gb:| **Bundled product**
| |:de:| Enthaltenes Produkt
- A bundled product is a product that is automatically put into the cart when another product is purchased. It's
similar to an add-on product, except that the customer has no choice between whether it is added or which of a
set of product is added.
* - | |:gb:| **Question**
| |:de:| Frage
- A question is a custom field that customers need to fill in when purchasing a specific product.
* - | |:gb:| **Voucher**
| |:de:| Gutschein
- A voucher is a code that can be used for multiple purposes: To grant a discount to specific customers, to only
show certain products to certain customers, or to keep a seat open for someone specific even though you are
sold out. If a voucher is used to apply a discount, the price of the purchased product is reduced by the
* - | |:gb:| **(Automatic) Discount**
| |:de:| (Automatischer) Rabatt
- Discounts can be used to automatically provide discounts to customers if their cart satisfies a certain condition.
* - | |:gb:| **Gift card**
| |:de:| Wertgutschein
- A :ref:`gift card <giftcards>` is a coupon representing an exact amount of money that can be used for purchases
of any kind. Gift cards can be sold, created manually, or used as a method to refund your customer without paying
them back directly.
Unlike a voucher, it does not reduce the price of the purchased products when redeemed, but instead works as a
payment method to lower the amount that needs to be paid through other methods. Gift cards are specific to an
organizer by default but can even by shared between organizers.
* - | |:gb:| **Cart**
| |:de:| Warenkorb
- A cart is a collection of products that are reserved by a customer who is currently completing the checkout
process, but has not yet finished it.
* - | |:gb:| **Order**
| |:de:| Bestellung
- An order is a purchase by a client, containing multiple different products. An order goes through various
states and can change during its lifetime.
* - | |:gb:| **Order code**
| |:de:| Bestellnummer
- An order code is the unique identifier of an order, usually consisting of 5 numbers and letters.
* - | |:gb:| **Customer**
| |:de:| Kund\*in
- A customer is the person who buys a ticket, regardless of who will be using it later. A customer can be defined
just by an email address or a name, or can have a persistent **customer account** they can log in to.
* - | |:gb:| **Order position**
| |:de:| Bestellposition
- An order position is a single line inside an order, representing the purchase of one specific product. If the
product is an admission product, this represents an attendee.
* - | |:gb:| **Attendee**
| |:de:| Teilnehmer\*in
- An attendee is the person designated to use a specific order position to access the event. It may be the same
or a different person as the customer.
* - | |:gb:| **Fee**
| |:de:| Gebühr
- A fee is an additional type of line inside an order that represents a cost that needs to be paid by the customer,
but is not related to a specific product. A typical example is a shipping fee.
* - | |:gb:| **Invoice** and **Cancellation**
| |:de:| Rechnung und Rechnungskorrektur
- An invoice refers to a legal document created to document a purchase for tax purposes. Invoices have individual
numbers and no longer change after they have been issued. Every invoice is connected to an order, but an order
can have multiple invoices: If an order changes, a cancellation document is created for the old invoice and a
new invoice is created.
* - | |:gb:| **Membership**
| |:de:| Mitgliedschaft
- A membership is a status attached customer, granting that customer a special right for a limited amount of time.
This special right could for example be the right to purchase a specific product. Memberships can be sold through
pretix as well.
* - | |:gb:| **Check-in**
| |:de:| Check-in
- A check-in is the event of someone's ticket being scanned at an entry or exit of the event.
* - | |:gb:| **Check-in list**
| |:de:| Check-in-Liste
- A check-in list is used to configure who can be scanned at a specific entry or exit of the event. Check-in lists
are isolated from each other, so by default each ticket is valid once on every check-in list individually. They
are therefore often used to represent *parts* of an event, either time-wise (e.g. conference days) or space-wise
(e.g. rooms).
* - | |:gb:| **Plugin**
| |:de:| Erweiterung
- A plugin is an optional software module that contains additional functionality and can be turned on and off per
event. If you host pretix on your own server, most plugins need to be installed separately.
* - | |:gb:| **Tax rule**
| |:de:| Steuer-Regel
- A tax rule defines how sales taxes are calculated for a product, possibly depending on type and country of the
customer.
* - | |:gb:| **Ticket**
| |:de:| Ticket
- A ticket usually refers to the actual file presented to the customer to be used at check-in, i.e. the PDF or
Passbook file carrying the QR code. In some cases, "ticket" may also be used to refer to an order position,
especially in case of admission products.
* - | |:gb:| **Ticket secret**
| |:de:| Ticket-Code
- The ticket secret (sometimes "ticket code") is what's contained in the QR code on the ticket.
* - | |:gb:| **Badge**
| |:de:| Badge
- A badge refers to the file used as a name tag for an attendee of your event.
* - | |:gb:| **User**
| |:de:| Benutzer
- A user is anyone who can sign into the backend interface of pretix. Not to be confused with *Customer*.
* - | |:gb:| **Team**
| |:de:| Team
- A :ref:`team <user-teams>` is a collection of users who are granted some level of access to a set of events.
* - | |:gb:| **Device**
| |:de:| Gerät
- A device is something that talks to pretix but does not run on a server. Usually a device refers to an
installation of pretixSCAN, pretixPOS or some compatible third-party app on one of your computing devices.
* - | |:gb:| **Gate**
| |:de:| Station
- A gate is a location at your event where people are being scanned, e.g. an entry or exit door. You can configure
gates in pretix to group multiple devices together that are used in the same location, mostly for statistical
purposes.
* - | |:gb:| **Widget**
| |:de:| Widget
- The :ref:`widget` is a JavaScript component that can be used to embed the shop of an event or a list of events
into a third-party web page.
* - | |:gb:| **Sales channel**
| |:de:| Verkaufskanal
- A sales channel refers to the type in which a purchase arrived in the system, e.g. through pretix' web shop itself,
or through other channels like box office or reseller sales.
* - | |:gb:| **Box office**
| |:de:| Abendkasse
- Box office purchases refer to all purchases made in-person from the organizer directly, through a point of sale
system like pretixPOS.
* - | |:gb:| **Reseller**
| |:de:| Vorverkaufsstelle
- Resellers are third-party entities offering in-person sales of events to customers.

20
doc/user/index.rst
View File

@@ -1,20 +0,0 @@
User Guide
==========
This section of our documentation is dedicated to show you the way around pretix if you are an event organizer
wanting to use pretix to sell tickets.
.. toctree::
:maxdepth: 2
organizers/index
events/create
events/settings
events/structureguide
events/widget
customers/index
events/giftcards
faq
markdown
android-version-support
glossary

169
doc/user/markdown.rst
View File

@@ -1,169 +0,0 @@
.. _markdown-guide:
Markdown Guide
==============
What is markdown?
-----------------
In many places of your shop, like frontpage texts, product descriptions and email texts, you can use
`Markdown`_ to create links, bold text, and other formatted content. Markdown is a good middle-ground
since it is way easier to learn than languages like HTML but allows all basic formatting options required
for text in those places.
.. note:: Some fields that are used in one-line context only allow formatting that refers to individual words
(such as bold or italic font or a link) but do not allow block-level formatting like lists or headlines.
Formatting rules
----------------
Simple text formatting
""""""""""""""""""""""
To set a text in italics, you can put it in asterisks or underscores. For example,
.. code-block:: markdown
Please *really* pay your _ticket_.
will become:
Please *really* pay your *ticket*.
If you set double asterisks or underscores, the text will be printed in bold. For example,
.. code-block:: markdown
This is **important**.
will become:
This is **important**.
You can also display, for example:
.. code-block:: markdown
Input this `exactly like this`.
You will get:
Input this ``exactly like this``.
Links
"""""
You can create a link by just pasting it in, e.g.
.. code-block:: markdown
Check this on https://en.wikipedia.org
will become:
Check this on https://en.wikipedia.org
However, if you want to control the text of the link, you can put the text of the link in ``[]`` brackets and the
link target in ``()`` parentheses, like this:
.. code-block:: markdown
Check this on [Wikipedia](https://en.wikipedia.org).
This will yield:
Check this on `Wikipedia`_
All links created with pretix Markdown syntax will open in a new tab.
Lists
"""""
You can create un-numbered lists by prepending the lines with asterisks.
.. code-block:: markdown
* First item
* Second item with a text that is too long to
fit in a line
* Third item
will become:
* First item
* Second item with a text that is too long to
fit in a line
* Third item
You can also use numbers as list items
.. code-block:: markdown
1. Red
2. Green
3. Blue
to get
1. Red
2. Green
3. Blue
Headlines
"""""""""
To create a headline, prepend it with ``#`` for the main headline, ``##`` for a headline of the second level,
and so on. For example:
.. code-block:: markdown
# Headline 1
## Headline 2
### Headline 3
#### Headline 4
##### Headline 5
###### Headline 6
We do not recommend using headlines of the first level, as pretix will already set the name of your event as a level-1
headline of the page and HTML pages should have only one headline on the first level.
You can also use
.. code-block:: markdown
*****
to create a horizontal line, like the following:
.. raw:: html
<hr>
Using HTML
----------
You can also directly embed HTML code, if you want, although we recommend
using Markdown, as it enables e.g. people using text-based email clients
to get a better plain text representation of your text. Note however, that for
security reasons you can only use the following HTML elements::
a, abbr, acronym, b, br, code, div, em, h1, h2,
h3, h4, h5, h6, hr, i, li, ol, p, pre, s, span, strong,
table, tbody, td, thead, tr, ul
Additionally, only the following attributes are allowed on them::
<a href="…" title="…">
<abbr title="…">
<acronym title="…">
<table width="…">
<td width="…" align="…">
<div class="…">
<p class="…">
<span class="…">
All other elements and attributes will be stripped during parsing.
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
.. _Wikipedia: https://en.wikipedia.org

43
doc/user/organizers/account.rst
View File

@@ -1,43 +0,0 @@
Organizer account
=================
The basis of all your operations within pretix is your organizer account. It represents an entity that is running
events, for example a company, yourself or any other institution.
Every event belongs to one organizer account and events within the same organizer account are assumed to belong together
in some sense, whereas events in different organizer accounts are completely isolated.
If you want to use the hosted pretix service, you can create an organizer account on our `Get started`_ page. Otherwise,
ask your pretix administrator for access to an organizer account.
You can find out all organizer accounts you have access to by going to your global dashboard (click on the pretix logo
in the top-left corner) and then select "Organizers" from the navigation bar on the left side. Then, choose one of the
organizer accounts presented, if there are multiple of them:
.. thumbnail:: ../../screens/organizer/list.png
:align: center
:class: screenshot
This overview shows you all event that belong to the organizer and you have access to:
.. thumbnail:: ../../screens/organizer/event_list.png
:align: center
:class: screenshot
With the "Edit" button at the top, next to the organizer account name, you can modify properties of the organizer
account such as its name and display settings for the public profile page of the organizer account:
.. thumbnail:: ../../screens/organizer/edit.png
:align: center
:class: screenshot
.. tip::
The profile page will be shown as ``https://pretix.eu/slug/`` where ``slug`` is to be replaced by the short form of
the organizer name that you entered during account creation and ``pretix.eu`` is to be replaced by your
installation's domain name if you are not using our hosted service.
Instead, you can also use a custom domain for the profile page and your events, for example
``https://tickets.example.com/`` if ``example.com`` is a domain that you own. Head to :ref:`custom_domain` to learn
more.
.. _Get started: https://pretix.eu/about/en/setup

47
doc/user/organizers/domain.rst
View File

@@ -1,47 +0,0 @@
.. _custom_domain:
Using a custom domain
=====================
By default, event shops built with pretix are accessible at ``https://<domain>/<organizer>/<event>/``, where
``<domain>`` is ``pretix.eu`` if you are using our hosted service and ``<organizer>`` and ``<event>`` are the short
form versions of your organizer account name and event name, respectively.
However, you are also able to use a custom domain for your ticket shops! If you work for "Awesome Party Corporation"
and your website is ``awesomepartycorp.com``, you might want to sell your tickets at ``tickets.awesomepartycorp.com``
and with pretix, you can do this. On this page, you find out the necessary steps to take.
With the pretix.eu hosted service
---------------------------------
Go to "Organizers" in the backend and select your organizer account. Then, go to "Settings" and "Custom Domain".
This page will show you instructions on how to set up your own domain. Basically, it works like this:
Go to the website of the provider you registered your domain name with. Look for the "DNS" settings page in their
interface. Unfortunately, we can't tell you exactly how that is named and how it looks, since it is different for every
domain provider.
Use this interface to add a new subdomain record, e.g. ``tickets`` of the type ``CNAME`` (might also be called "alias").
The value of the record should be the one shown on the "Custom Domain" page in pretix' backend.
Submit your changes and wait a bit, it can regularly take up to three hours for DNS changes to propagate to the caches
of all DNS servers. You can try checking by accessing your new subdomain, ``http://tickets.awesomepartycorp.com``.
If DNS was changed successfully, you should see a SSL certificate error. If you ignore the error and access the page
anyways, you should get a pretix-themed error page with the headline "Unknown domain".
Now, tell us about your domain on the "Custom Domain" page to get started.
With a custom pretix installation
---------------------------------
If you installed pretix on a server yourself, you can also use separate domains for separate organizers.
First of all, configure your webserver or reverse proxy to pass requests to the new domain to pretix as well.
Then, go to the organizer account in pretix and click the "Edit" button. Enter the new domain in the "Custom Domain"
field, then you're done!
.. thumbnail:: ../../screens/organizer/edit_sysadmin.png
:align: center
:class: screenshot
Note that this field only shows up if you are logged in as a system administrator of your pretix installation.

9
doc/user/organizers/index.rst
View File

@@ -1,9 +0,0 @@
Organizer accounts and teams
============================
.. toctree::
:maxdepth: 2
account
teams
domain

71
doc/user/organizers/teams.rst
View File

@@ -1,71 +0,0 @@
.. _user-teams:
Teams
=====
We don't expect you to work on your events all by yourself and therefore, pretix comes with ways to invite your fellow
team members to access your pretix organizer account. To manage teams, click on the "Teams" link on your organizer
settings page (see above how to find it). This shows you a list of teams that should contain at least one team already:
.. thumbnail:: ../../screens/organizer/team_list.png
:align: center
:class: screenshot
If you click on a team name, you get to a page that shows you the current members of the team:
.. thumbnail:: ../../screens/organizer/team_detail.png
:align: center
:class: screenshot
You see that there is a list of pretix user accounts (i.e. email addresses), who are part of the team. To add a user to
the team, just enter their email address in the text box next to the "Add" button. If the user already has an account
in the pretix system they will instantly get access to the team. Otherwise, they will be sent an email with an invitation
link that can be used to create an account. This account will then instantly have access to the team. Users can be part
of as many teams as you want.
In the section below, you can also create access tokens for our :ref:`rest-api`. You can read more on this topic in the
section :ref:`rest-auth` of the API documentation.
Next to the team name, you again see a button called "Edit" that allows you to modify the permissions of the team.
Permissions separate into two areas:
* **Organizer permissions** allow actions on the level of an organizer account, in particular:
* Can create events – To create a new event under this organizer account, users need to have this permission
* Can manage customer accounts – This permission is required to view and change organizer-level customer accounts.
* Can change teams and permissions – This permission is required to perform the kind of action you are doing right now.
Anyone with this permission can assign arbitrary other permissions to themselves, so this is the most powerful
permission there is to give.
* Can change organizer settings – This permission is required to perform changes to the settings of the organizer
account, e.g. its name or display settings.
* **Event permissions** allow actions on the level of an event. You can give the team access to all events of the
organizer (including future ones that are not yet created) or just a selected set of events. The specific permissions to choose from are:
* Can change event settings – This permission gives access to most areas of the control panel that are not controlled
by one of the other event permissions, especially those that are related to setting up and configuring the event.
* Can change product settings – This permission allows to create and modify products and objects that are closely
related to products, such as product categories, quotas, and questions.
* Can view orders – This permission allows viewing the list of orders and all individual order details, but not
changing anything about it. This also includes the various exports offered.
* Can change orders – This permission allows all actions that involve changing an order, such as changing the products
in an order, marking an order as paid or refunded, importing banking data, etc. This only works properly if the
same users also have the "Can view orders" permission.
* Can view vouchers – This permission allows viewing the list of vouchers including the voucher codes themselves and
their redemption status.
* Can perform check-ins – This permission allows using web-based features to perform ticket search and check-in.
* Can change vouchers – This permission allows to create and modify vouchers in all their details. It only works
properly if the same users also have the "Can view vouchers" permission.
.. thumbnail:: ../../screens/organizer/team_edit.png
:align: center
:class: screenshot

38
doc/user/payments/banktransfer.rst
View File

@@ -1,38 +0,0 @@
.. _`banktransfer`:
Bank transfer
=============
To accept payments with bank transfer, you only need to fill out one important field in pretix' settings: In "Bank
account details" you should specify everything one needs to know to transfer money to you, e.g. your IBAN and BIC,
the name of your bank and for international transfers, preferably also your address and the bank's address.
pretix will automatically tell the user to include the order code in the payment reference so incoming transfers can
automatically be matched to payments.
Importing payment data
----------------------
The easiest way to import payment data is to download a CSV file from your online banking. Most banks provide a CSV
export of some sort. You can go to "Import bank data" in pretix to upload a new file:
.. image:: img/bank1.png
:class: screenshot
If you upload a file for the first time, pretix will not know what information is contained in which column as every
bank builds completely different CSV files. Therefore, pretix will ask you for that information. It will show you the
data of the file you imported and ask you to define the column's meanings. You can select one column that contains
the payment date and one that contains the paid amount. You can select multiple columns that contain information
about the payer or the payment reference. All other columns will be ignored.
Once you continue, pretix will try to match the payments to the respective orders automatically. It will tell you how
many orders could be processed correctly and how many could not. You can then go back to the upload page to see all
transfers from your bank statement that are not yet matched to an order. Using the input field and the buttons on the
left of each transaction, you can manually enter an order code to match it to or just discard it from the list, e.g.
if the transaction is not related to the event at all.
.. tip:: If you aren't afraid of getting a bit more technical and your bank supports the HBCI/FinTS protocol (as most
German banks do), you can use `pretix-banktool`_ to fully automate this process.
.. _pretix-banktool: https://github.com/pretix/pretix-banktool

63
doc/user/payments/fees.rst
View File

@@ -1,63 +0,0 @@
.. _payment-fees:
Payment method fees
===================
Most external payment providers like PayPal or Stripe charge substantial fees for your service. In general, you have
two options to deal with this:
1. Pay the fees yourself
2. Add the fees to your customer's total
The choice totally depends on you and what your customers expect from you. Option two might be appropriate if you
offer different payment methods and want to encourage your customers to use the ones that come you cheaper, but you
might also decide to go for option one to make it easier for customers who don't have the option.
.. warning:: Please note that EU Directive 2015/2366 bans surcharging payment fees for most common payment
methods within the European Union. Depending on the payment method, this might affect
selling to consumers only or to business customers as well. Depending on your country, this
legislation might already be in place or become relevant from January 2018 the latest. This is not
legal advice. If in doubt, consult a lawyer or refrain from charging payment fees.
If you go for the first option (as you should in the EU), you can just leave the payment fee fields in pretix' settings
empty.
If you go for the second option, you can configure pretix to charge the payment method fees to your user. You can
define both an absolute fee as well as a percental fee based on the order total. If you do so, there are two
different ways in which pretix can calculate the fee. Normally, it is fine to just go with the default setting, but
in case you are interested, here are all the details:
Payment fee calculation
-----------------------
If you configure a fee for a payment method, there are two possible ways for us to calculate this. Let's
assume that your payment provider, e.g. PayPal, charges you 5 % fees and you want to charge your users the
same 5 %, such that for a ticket with a list price of 100 € you will get your full 100 €.
**Method A: Calculate the fee from the subtotal and add it to the bill.**
For a ticket price of 100 €, this will lead to the following calculation:
============================================== ============
Ticket price 100.00 €
pretix calculates the fee as 5 % of 100 € +5.00 €
Subtotal that will be paid by the customer 105.00 €
PayPal calculates its fee as 5 % of 105 € -5.25 €
End total that is on your bank account **99.75 €**
============================================== ============
**Method B (default): Calculate the fee from the total value including the fee.**
For a ticket price of 100 €, this will lead to the following calculation:
===================================================== =============
Ticket price 100.00 €
pretix calculates the fee as 100/(100 - 5) % of 100 € +5.26 €
Subtotal that will be paid by the customer 105.26 €
PayPal calculates its fee as 5 % of 105 € -5.26 €
End total that is on your bank account **100.00 €**
===================================================== =============
Due to the various rounding steps performed by pretix and by the payment provider, the end total on
your bank account might still vary by one cent.

BIN
doc/user/payments/img/bank1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 30 KiB

BIN
doc/user/payments/img/bank2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

BIN
doc/user/payments/img/paypal1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 95 KiB

BIN
doc/user/payments/img/paypal2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
doc/user/payments/img/paypal3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 89 KiB

BIN
doc/user/payments/img/paypal4.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 89 KiB

BIN
doc/user/payments/img/paypal5.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 72 KiB

BIN
doc/user/payments/img/paypal6.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 94 KiB

BIN
doc/user/payments/img/paypal7.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 94 KiB

BIN
doc/user/payments/img/paypal8.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 105 KiB

BIN
doc/user/payments/img/paypal_pretix.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

BIN
doc/user/payments/img/stripe1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 81 KiB

BIN
doc/user/payments/img/stripe2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 81 KiB

13
doc/user/payments/index.rst
View File

@@ -1,13 +0,0 @@
Payment settings
================
.. toctree::
:maxdepth: 2
settings
overview
fees
paypal
stripe
banktransfer

16
doc/user/payments/overview.rst
View File

@@ -1,16 +0,0 @@
Payment method overview
=======================
pretix allows you to accept payments using a variety of payment methods to fit the needs of very different events.
This page gives you a short overview over them and links to more detailed descriptions in some cases.
Payment methods are built as pretix plugins. For this reason, you might first need to enable a certain plugin at
"Settings" → "Plugins" in your event settings. Then, you can configure them in detail at "Settings" → "Payment".
If you host pretix on your own server, you might need to install a plugin first for some of the payment methods listed
on this page as well as for additional ones.
To get an overview of the officially supported payment methods and their pros and cons, head to the `pretix website`_.
On these pages, you get more information on how to configure :ref:`stripe`, :ref:`paypal`, and :ref:`banktransfer`.
.. _pretix website: https://pretix.eu/about/en/features/payment

71
doc/user/payments/paypal.rst
View File

@@ -1,71 +0,0 @@
.. _`paypal`:
PayPal
======
.. note::
If you use pretix Hosted, you do not longer need to go through this tedious process! You can
just open the PayPal settings in the payment section of your event, click "Connect to PayPal"
and log in to your PayPal account. The following guide is only required for self-hosted
versions of pretix.
To integrate PayPal with pretix, you first need to have an active PayPal merchant account. If you do not already have a
PayPal account, you can create one on `paypal.com`_.
If you look into pretix' settings, you are required to fill in two keys:
.. image:: img/paypal_pretix.png
:class: screenshot
Unfortunately, it is not straightforward how to get those keys from PayPal's website. In order to do so, you
need to go to `developer.paypal.com`_ to link the account to your pretix event.
.. warning::
Unfortunately, PayPal tries to confuse you by having multiple APIs with different keys. You really need to
go to https://developer.paypal.com for the API we use, not to your normal account settings!
Click on "Log In" in the top-right corner and log in with your PayPal account.
.. image:: img/paypal2.png
:class: screenshot
Then, click on "Dashboard" in the top-right corner.
.. image:: img/paypal3.png
:class: screenshot
In the dashboard, scroll down until you see the headline "REST API Apps". Click "Create App".
.. image:: img/paypal4.png
:class: screenshot
Enter any name for the application that helps you to identify it later. Then confirm with "Create App".
.. image:: img/paypal5.png
:class: screenshot
On the next page, before you do anything else, switch the mode on the right to "Live" to get the correct keys.
Then, copy the "Client ID" and the "Secret" and enter them into the appropriate fields in the payment settings in
pretix.
.. image:: img/paypal6.png
:class: screenshot
Finally, we need to create a webhook. The webhook tells PayPal to notify pretix e.g. if a payment gets cancelled so
pretix can cancel the ticket as well. If you have multiple events connected to your PayPal account, you need multiple
webhooks. To create one, scroll a bit down and click "Add Webhook".
.. image:: img/paypal7.png
:class: screenshot
Then, enter the webhook URL that you find on the pretix settings page. If you use pretix Hosted, this is always ``https://pretix.eu/_paypal/webhook/``.
Tick the box "All events" and save.
.. image:: img/paypal8.png
:class: screenshot
That's it, you are ready to go!
.. _paypal.com: https://www.paypal.com/webapps/mpp/account-selection
.. _developer.paypal.com: https://developer.paypal.com/

65
doc/user/payments/settings.rst
View File

@@ -1,65 +0,0 @@
General settings
================
At "Settings" → "Payment", you can configure every aspect related to the payments you want to accept. The "Deadline"
and "Advanced" tabs of the page show a number of general settings that affect all payment methods:
.. thumbnail:: ../../screens/event/settings_payment.png
:align: center
:class: screenshot
In particular, these are:
Payment term in days
If a order has been created, it is supposed to be paid within this number of days. Of course, some payment methods
(like credit card) succeed immediately in most cases, but others don't (like bank transfer) and even credit card
payments might fail and you might want to give the customer a chance to try another credit card before losing their
ticket. Therefore, we recommend setting a few days here. If you are accepting bank transfers, we wouldn't recommend
less than 10 days.
Last date of payments
There is probably no use for payments received after your event, so you can set a date that the payment deadline of
a new order will never exceed. This has precedence over the number of days configured above, so if I create an order
two days before the configured last date of payments, my payment term will only be two days, not ten. If you have
payment methods that always require some time (like bank transfer), you will later be able to selectively disable them
once the event comes closer.
Only end payment terms on weekdays
If you check this box, the payment term calculated by the number of days configured above will never end on a Saturday
or a Sunday. If it technically would do so, the term is extended to the next Monday. Note that this currently does not
take into account national or bank holidays in your country.
Automatically expire unpaid orders
If you check this box, orders will automatically go into "expired" state if the payment term is over and no payment
has been received. This means that the tickets will no longer be reserved for the customer and someone else can buy
them from the shop again. If you do not check this box, tickets do not become available again automatically, but you
can mark orders as expired manually.
Accept late payments
If you check this box, incoming payments will accepted even if the order is in "expired" state -- as long as there
still is sufficient quota available and the last date of payments is not yet over. We recommend to check this in most
cases.
Tax rule for payment fees
If you pass on the payment method fees to your customers, you will most likely also need to pay sales tax on those
fees. Here, you can configure the tax rate. Read :ref:`taxes` for more information.
Below, you can configure the details of the various payment methods. You can find information on their different settings
on the next pages of this documentation, but there are a few things most of them have in common:
Enable payment method
Check this box to allow customers to use this method. At least one method needs to be active to process non-free orders.
Additional fee (absolute and percentage), Calculate the fee from the total value including the fee
These fields allow you to pass fees on to your customers instead of paying them yourselves. Read :ref:`payment-fees`
for documentation on how this behaves.
Available until
This allows you to set a date at which this payment method will automatically become disabled. This is useful if you
want people to be able to pay by card on the day before your event, but not by bank transfer, because it would not
arrive in time.
Text on invoices
If you are using pretix' invoicing feature, this is a text that will be printed on every invoice for an order that
uses this payment method. You could use this to tell the accounting department of the invoice receiver that the payment
has already been received online or that it should be performed via bank transfer.

34
doc/user/payments/stripe.rst
View File

@@ -1,34 +0,0 @@
.. _stripe:
Stripe
======
.. note:: If you use the Hosted version of pretix at pretix.eu, you do not need to copy API keys and create webhooks
any more. Instead, you can just click "Connect with Stripe" in pretix and everything will connect
automatically.
To integrate Stripe with pretix, you first need to have an active Stripe merchant account. If you do not already have a
Stripe account, you can create one on `stripe.com`_. Then, click on "API" in the left navigation of the Stripe
Dashboard. As you can see in the following screenshot, you will be presented with two sets of API keys, one for test
and one for live payments. In each set, there is a secret and a publishable keys.
.. image:: img/stripe1.png
:class: screenshot
Choose one of the two sets and copy the two keys to the appropriate fields in pretix' settings. To perform actual
payments, you will need to use the live keys, but you can use the test keys to test the payment flow before you go live.
In test mode, you cannot use your real credit card, but only `test cards`_ like ``4242424242424242`` that you can
find in Stripe's documentation.
If you want Stripe to notify pretix automatically once a payment gets cancelled, so pretix can cancel the ticket as
well, you need to create a so-called webhook. To do so, click "Webhooks" on top of the page in the Stripe dashboard
that you are currently on. Then, click "Add endpoint" and enter the URL that you find directly below the key
configuration in pretix' settings.
.. image:: img/stripe2.png
:class: screenshot
Again, you can choose between live mode and test mode here.
.. _stripe.com: https://dashboard.stripe.com/register
.. _test cards: https://stripe.com/docs/testing#cards