diff --git a/doc/api/resources/exhibitors.rst b/doc/api/resources/exhibitors.rst index 8f6a89a08b..6fe2d73045 100644 --- a/doc/api/resources/exhibitors.rst +++ b/doc/api/resources/exhibitors.rst @@ -844,3 +844,187 @@ You can also fetch existing leads (if you are authorized to do so): :statuscode 200: No error :statuscode 401: Invalid authentication code :statuscode 403: Not permitted to access bulk data + +Retrieving Vouchers +""""""""""""""""""" + +Vouchers returned by the App API use a different format than described in :ref:`rest-vouchers`. + +.. rst-class:: rest-resource-table + +===================================== ========================== ======================================================= +Field Type Description +===================================== ========================== ======================================================= +id integer Internal ID of the voucher +code string The voucher code that is required to redeem the voucher +max_usages integer The maximum number of times this voucher can be + redeemed (default: 1). +redeemed integer The number of times this voucher already has been + redeemed. +valid_until datetime The voucher expiration date (or ``null``). +subevent string Name of the date inside an event series this voucher belongs to (or ``null``). +tag string A string that is used for grouping vouchers +comment string An internal exhibitor comment on the voucher. +items list of strings A list of items this voucher is restricted to (or ``null``). +price_mode string Determines how this voucher affects product prices. + Possible values: + + * ``none`` – No effect on price + * ``set`` – The product price is set to the given ``value`` + * ``subtract`` – The product price is determined by the original price *minus* the given ``value`` + * ``percent`` – The product price is determined by the original price reduced by the percentage given in ``value`` +value decimal (string) The value (see ``price_mode``) +redemptions list of objects A list of objects, where each object represents an order position that has been purchased using the voucher. + Each entry will contains the fields ``attendee_fields``, ``redemption_date`` and ``subevent``. + + The attendee data in the ``attendee_fields`` that is shown is based on the event's configuration, and each entry + contains the fields ``id``, ``label``, ``value``, and ``details``. ``details`` is usually empty + except in a few cases where it contains an additional list of objects + with ``value`` and ``label`` keys (e.g. splitting of names). +===================================== ========================== ======================================================= + + +.. http:get:: /exhibitors/api/v1/vouchers/ + + Returns a list of all vouchers connected to the exhibitor. + + Note that the ``attendee_fields`` array can contain any number of dynamic keys! + Depending on the exhibitors permission and event configuration this might be empty, or contain lots of details. + The app should dynamically show these values (read-only) with the labels sent by the server. + + + **Example request**: + + .. sourcecode:: http + + GET /exhibitors/api/v1/vouchers/ 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, + "code": "43K6LKM37FBVR2YG", + "max_usages": 1, + "redeemed": 0, + "valid_until": null, + "subevent": null, + "tag": "testvoucher", + "comment": "", + "items": [ + "All" + ], + "price_mode": "set", + "value": "12.00", + "redemptions": [ + { + "attendee_fields": [ + { + "id": "attendee_name", + "label": "Name", + "value": "Jon Doe", + "details": [ + {"label": "Given name", "value": "John"}, + {"label": "Family name", "value": "Doe"}, + ] + }, + { + "id": "attendee_email", + "label": "Email", + "value": "test@example.com", + "details": [] + } + ], + "redemption_date": "2026-05-06", + "subevent": null + }, + ] + } + ] + } + + :statuscode 200: No error + :statuscode 401: Invalid authentication code + :statuscode 403: Not permitted to access bulk data + +.. http:get:: /exhibitors/api/v1/vouchers/(id)/ + + Returns the details of a single, specific voucher connected to the exhibitor. + + Note that the ``attendee_fields`` array can contain any number of dynamic keys! + Depending on the exhibitors permission and event configuration this might be empty, or contain lots of details. + The app should dynamically show these values (read-only) with the labels sent by the server. + + + **Example request**: + + .. sourcecode:: http + + GET /exhibitors/api/v1/vouchers/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, + "code": "43K6LKM37FBVR2YG", + "max_usages": 1, + "redeemed": 0, + "valid_until": null, + "subevent": null, + "tag": "testvoucher", + "comment": "", + "items": [ + "All" + ], + "price_mode": "set", + "value": "12.00", + "redemptions": [ + { + "attendee_fields": [ + { + "id": "attendee_name", + "label": "Name", + "value": "Jon Doe", + "details": [ + {"label": "Given name", "value": "John"}, + {"label": "Family name", "value": "Doe"}, + ] + }, + { + "id": "attendee_email", + "label": "Email", + "value": "test@example.com", + "details": [] + } + ], + "redemption_date": "2026-05-06", + "subevent": null + }, + ] + } + + :param id: The ``id`` field of the voucher to fetch + :statuscode 200: No error + :statuscode 401: Invalid authentication code + :statuscode 403: Not permitted to access bulk data + :statuscode 404: Voucher not found in system \ No newline at end of file