Item categories¶

Resource description¶

Categories provide grouping for items (better known as products). The category resource contains the following public fields:

Field	Type	Description
id	integer	Internal ID of the category
name	multi-lingual string	The category’s visible name
internal_name	string	An optional name that is only used in the backend
description	multi-lingual string	A public description (might include markdown, can be `null`)
position	integer	An integer, used for sorting the categories
is_addon	boolean	If `true`, items within this category are not on sale on their own but the category provides a source for defining add-ons for other products.
cross_selling_mode	string	If `null`, cross-selling is disabled for this category. If `"only"`, it is only visible in the cross-selling step. If `"both"`, it is visible on the normal index page as well. Only available if `is_addon` is `false`.
cross_selling_condition	string	Only relevant if `cross_selling_mode` is not `null`. If `"always"`, always show in cross-selling step. If `"products"`, only show if the cart contains one of the products listed in `cross_selling_match_products`. If `"discounts"`, only show products that qualify for a discount according to discount rules.
cross_selling_match_products	list of integer	Only relevant if `cross_selling_condition` is `"products"`. Internal ID of the items of which at least one needs to be in the cart for this category to be shown.

Endpoints¶

GET /api/v1/organizers/(organizer)/events/(event)/categories/¶

Returns a list of all categories within a given event.

Example request:

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

Example response:

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": {"en": "Tickets"},
      "internal_name": "",
      "description": {"en": "Tickets are what you need to get in."},
      "position": 1,
      "is_addon": false,
      "cross_selling_mode": null,
      "cross_selling_condition": null,
      "cross_selling_match_products": []
    }
  ]
}

Query Parameters:

page (integer) – The page number in case of a multi-page result set, default is 1
is_addon (boolean) – If set to true or false, only categories with this value for the field is_addon will be returned.
ordering (string) – Manually set the ordering of results. Valid fields to be used are id and position. Default: position

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event 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.

GET /api/v1/organizers/(organizer)/events/(event)/categories/(id)/¶

Returns information on one category, identified by its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "name": {"en": "Tickets"},
  "internal_name": "",
  "description": {"en": "Tickets are what you need to get in."},
  "position": 1,
  "is_addon": false,
  "cross_selling_mode": null,
  "cross_selling_condition": null,
  "cross_selling_match_products": []
}

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event to fetch
id – The id field of the category 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)/categories/¶

Creates a new category

Example request:

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

{
  "name": {"en": "Tickets"},
  "internal_name": "",
  "description": {"en": "Tickets are what you need to get in."},
  "position": 1,
  "is_addon": false,
  "cross_selling_mode": null,
  "cross_selling_condition": null,
  "cross_selling_match_products": []
}

Example response:

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

{
  "id": 1,
  "name": {"en": "Tickets"},
  "internal_name": "",
  "description": {"en": "Tickets are what you need to get in."},
  "position": 1,
  "is_addon": false,
  "cross_selling_mode": null,
  "cross_selling_condition": null,
  "cross_selling_match_products": []
}

Parameters:

organizer – The slug field of the organizer of the event to create a category for
event – The slug field of the event to create a category for

Status Codes:

201 Created – no error
400 Bad Request – The category 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)/categories/(id)/¶

Update a category. 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 field.

Example request:

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

{
  "is_addon": true
}

Example response:

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

{
  "id": 1,
  "name": {"en": "Tickets"},
  "internal_name": "",
  "description": {"en": "Tickets are what you need to get in."},
  "position": 1,
  "is_addon": true,
  "cross_selling_mode": null,
  "cross_selling_condition": null,
  "cross_selling_match_products": []
}

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 category to modify

Status Codes:

200 OK – no error
400 Bad Request – The category 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)/category/(id)/¶

Delete a category.

Example request:

DELETE /api/v1/organizers/bigevents/events/sampleconf/categories/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 category 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.