Item variations¶

Resource description¶

Variations of items can be use for products (items) that are available in different sizes, colors or other variations of the same product. The variations resource contains the following public fields:

Field	Type	Description
id	integer	Internal ID of the variation
default_price	money (string)	The price set directly for this variation or `null`
price	money (string)	The price used for this variation. This is either the same as `default_price` if that value is set or equal to the item’s `default_price` (read-only).
free_price_suggestion	money (string)	A suggested price, used as a default value if `Item.free_price` is set (or `null`).
original_price	money (string)	An original price, shown for comparison, not used for price calculations (or `null`).
active	boolean	If `false`, this variation will not be sold or shown.
description	multi-lingual string	A public description of the variation. May contain Markdown syntax or can be `null`.
position	integer	An integer, used for sorting
checkin_attention	boolean	If `true`, the check-in app should show a warning that this ticket requires special attention if such a variation is being scanned.
checkin_text	string	Text that will be shown if a ticket of this type is scanned (or `null`).
require_approval	boolean	If `true`, orders with this variation will need to be approved by the event organizer before they can be paid.
require_membership	boolean	If `true`, booking this variation requires an active membership.
require_membership_hidden	boolean	If `true` and `require_membership` is set, this variation will be hidden from users without a valid membership.
require_membership_types	list of integers	Internal IDs of membership types valid if `require_membership` is `true`
sales_channels	list of strings	Sales channels this variation is available on, such as `"web"` or `"resellers"`. Defaults to all existing sales channels. The item-level list takes precedence, i.e. a sales channel needs to be on both lists for the item to be available.
available_from	datetime	The first date time at which this variation can be bought (or `null`).
available_from_mode	string	If `hide` (the default), this variation is hidden in the shop if unavailable due to the available_from setting. If `info`, the variation is visible, but can’t be purchased, and a note explaining the unavailability is displayed.
available_until	datetime	The last date time at which this variation can be bought (or `null`).
available_until_mode	string	If `hide` (the default), this variation is hidden in the shop if unavailable due to the available_until setting. If `info`, the variation is visible, but can’t be purchased, and a note explaining the unavailability is displayed.
hide_without_voucher	boolean	If `true`, this variation is only shown during the voucher redemption process, but not in the normal shop frontend.
meta_data	object	Values set for event-specific meta data parameters.

Changed in version 4.16: The meta_data and checkin_attention attributes have been added.

Changed in version 2023.10: The free_price_suggestion attribute has been added. The checkin_text attribute has been added.

Endpoints¶

GET /api/v1/organizers/(organizer)/events/(event)/items/(item)/variations/¶

Returns a list of all variations for a given item.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/items/11/variations/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "value": {
        "en": "S"
      },
      "active": true,
      "checkin_attention": false,
      "checkin_text": null,
      "require_approval": false,
      "require_membership": false,
      "require_membership_hidden": false,
      "require_membership_types": [],
      "sales_channels": ["web"],
      "available_from": null,
      "available_from_mode": "hide",
      "available_until": null,
      "available_until_mode": "hide",
      "hide_without_voucher": false,
      "description": {
        "en": "Test2"
      },
      "position": 0,
      "default_price": "223.00",
      "price": 223.0,
      "original_price": null,
      "free_price_suggestion": null,
      "meta_data": {}
    },
    {
      "id": 3,
      "value": {
        "en": "L"
      },
      "active": true,
      "checkin_attention": false,
      "checkin_text": null,
      "require_approval": false,
      "require_membership": false,
      "require_membership_hidden": false,
      "require_membership_types": [],
      "sales_channels": ["web"],
      "available_from": null,
      "available_from_mode": "hide",
      "available_until": null,
      "available_until_mode": "hide",
      "hide_without_voucher": false,
      "description": {},
      "position": 1,
      "default_price": "223.00",
      "price": 223.0,
      "original_price": null,
      "free_price_suggestion": null,
      "meta_data": {}
    }
  ]
}

Query Parameters:

page (integer) – The page number in case of a multi-page result set, default is 1
active (boolean) – If set to true or false, only items with this value for the field active will be returned.

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event to fetch
item – The id field of the item to fetch

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event/item does not exist or you have no permission to view this resource.

GET /api/v1/organizers/(organizer)/events/(event)/items/(item)/variations/(id)/¶

Returns information on one variation, identified by its ID.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/items/1/variations/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 3,
  "value": {
        "en": "Student"
  },
  "default_price": "10.00",
  "price": "10.00",
  "original_price": null,
  "free_price_suggestion": null,
  "active": true,
  "checkin_attention": false,
  "checkin_text": null,
  "require_approval": false,
  "require_membership": false,
  "require_membership_hidden": false,
  "require_membership_types": [],
  "sales_channels": ["web"],
  "available_from": null,
  "available_from_mode": "hide",
  "available_until": null,
  "available_until_mode": "hide",
  "hide_without_voucher": false,
  "description": null,
  "position": 0,
  "meta_data": {}
}

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event to fetch
item – The id field of the item to fetch
id – The id field of the variation to fetch

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.

POST /api/v1/organizers/(organizer)/events/(event)/items/(item)/variations/¶

Creates a new variation

Example request:

POST /api/v1/organizers/bigevents/events/sampleconf/items/1/variations/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json

{
  "value": {"en": "Student"},
  "default_price": "10.00",
  "active": true,
  "checkin_attention": false,
  "checkin_text": null,
  "require_approval": false,
  "require_membership": false,
  "require_membership_hidden": false,
  "require_membership_types": [],
  "sales_channels": ["web"],
  "available_from": null,
  "available_from_mode": "hide",
  "available_until": null,
  "available_until_mode": "hide",
  "hide_without_voucher": false,
  "description": null,
  "position": 0,
  "meta_data": {}
}

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "value": {"en": "Student"},
  "default_price": "10.00",
  "price": "10.00",
  "original_price": null,
  "free_price_suggestion": null,
  "active": true,
  "checkin_attention": false,
  "checkin_text": null,
  "require_approval": false,
  "require_membership": false,
  "require_membership_hidden": false,
  "require_membership_types": [],
  "sales_channels": ["web"],
  "available_from": null,
  "available_from_mode": "hide",
  "available_until": null,
  "available_until_mode": "hide",
  "hide_without_voucher": false,
  "description": null,
  "position": 0,
  "meta_data": {}
}

Parameters:

organizer – The slug field of the organizer of the event/item to create a variation for
event – The slug field of the event to create a variation for
item – The id field of the item to create a variation for

Status Codes:

201 Created – no error
400 Bad Request – The variation could not be created due to invalid submitted data.
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to create this resource.

PATCH /api/v1/organizers/(organizer)/events/(event)/items/(item)/variations/(id)/¶

Update a variation. You can also use PUT instead of PATCH. With PUT, you have to provide all fields of the resource, other fields will be reset to default. With PATCH, you only need to provide the fields that you want to change.

You can change all fields of the resource except the id and the price field.

Example request:

PATCH /api/v1/organizers/bigevents/events/sampleconf/items/1/variations/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 94

{
  "active": false,
  "position": 1
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "value": {"en": "Student"},
  "default_price": "10.00",
  "price": "10.00",
  "original_price": null,
  "free_price_suggestion": null,
  "active": false,
  "checkin_attention": false,
  "checkin_text": null,
  "require_approval": false,
  "require_membership": false,
  "require_membership_hidden": false,
  "require_membership_types": [],
  "sales_channels": ["web"],
  "available_from": null,
  "available_from_mode": "hide",
  "available_until": null,
  "available_until_mode": "hide",
  "hide_without_voucher": false,
  "description": null,
  "position": 1,
  "meta_data": {}
}

Parameters:

organizer – The slug field of the organizer to modify
event – The slug field of the event to modify
id – The id field of the item to modify
id – The id field of the variation to modify

Status Codes:

200 OK – no error
400 Bad Request – The variation could not be modified due to invalid submitted data
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to change this resource.

DELETE /api/v1/organizers/(organizer)/events/(event)/items/(id)/variations/(id)/¶

Delete a variation.

Example request:

DELETE /api/v1/organizers/bigevents/events/sampleconf/items/1/variations/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 204 No Content
Vary: Accept

Parameters:

organizer – The slug field of the organizer to modify
event – The slug field of the event to modify
id – The id field of the item to modify
id – The id field of the variation to delete

Status Codes:

204 No Content – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to delete this resource.