.. _`rest-categories`: Item categories =============== Resource description -------------------- Categories provide grouping for items (better known as products). The category resource contains the following public fields: .. rst-class:: rest-resource-table ===================================== ========================== ======================================================= 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 --------- .. http:get:: /api/v1/organizers/(organizer)/events/(event)/categories/ Returns a list of all categories within a given event. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/categories/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http 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 integer page: The page number in case of a multi-page result set, default is 1 :query boolean is_addon: If set to ``true`` or ``false``, only categories with this value for the field ``is_addon`` will be returned. :query string ordering: Manually set the ordering of results. Valid fields to be used are ``id`` and ``position``. Default: ``position`` :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. .. http:get:: /api/v1/organizers/(organizer)/events/(event)/categories/(id)/ Returns information on one category, identified by its ID. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/categories/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http 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": [] } :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :param id: The ``id`` field of the category to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. .. http:post:: /api/v1/organizers/(organizer)/events/(event)/categories/ Creates a new category **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http 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": [] } :param organizer: The ``slug`` field of the organizer of the event to create a category for :param event: The ``slug`` field of the event to create a category for :statuscode 201: no error :statuscode 400: The category could not be created due to invalid submitted data. :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to create this resource. .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http 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": [] } :param organizer: The ``slug`` field of the organizer to modify :param event: The ``slug`` field of the event to modify :param id: The ``id`` field of the category to modify :statuscode 200: no error :statuscode 400: The category could not be modified due to invalid submitted data :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to change this resource. .. http:delete:: /api/v1/organizers/(organizer)/events/(event)/category/(id)/ Delete a category. **Example request**: .. sourcecode:: http DELETE /api/v1/organizers/bigevents/events/sampleconf/categories/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 204 No Content Vary: Accept :param organizer: The ``slug`` field of the organizer to modify :param event: The ``slug`` field of the event to modify :param id: The ``id`` field of the category to delete :statuscode 204: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to delete this resource.