.. _`rest-vouchers`: Vouchers ======== Resource description -------------------- The voucher resource contains the following public fields: .. 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. min_usages integer The minimum number of times this voucher must be redeemed on first usage (default: 1). valid_until datetime The voucher expiration date (or ``null``). block_quota boolean If ``true``, quota is blocked for this voucher. allow_ignore_quota boolean If ``true``, this voucher can be redeemed even if a product is sold out and even if quota is not blocked for this voucher. 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``) item integer An ID of an item this voucher is restricted to (or ``null``) variation integer An ID of a variation this voucher is restricted to (or ``null``) quota integer An ID of a quota this voucher is restricted to (or ``null``). This is an exclusive alternative to ``item`` and ``variation``: A voucher can be attached either to a specific product or to all products within one quota or it can be available for all items without restriction. seat string ``seat_guid`` attribute of a specific seat (or ``null``) tag string A string that is used for grouping vouchers comment string An internal comment on the voucher subevent integer ID of the date inside an event series this voucher belongs to (or ``null``). show_hidden_items boolean Only if set to ``true``, this voucher allows to buy products with the property ``hide_without_voucher``. Defaults to ``true``. all_addons_included boolean If set to ``true``, all add-on products for the product purchased with this voucher are included in the base price. all_bundles_included boolean If set to ``true``, all bundled products for the product purchased with this voucher are added without their designated price. ===================================== ========================== ======================================================= Endpoints --------- .. http:get:: /api/v1/organizers/(organizer)/events/(event)/vouchers/ Returns a list of all vouchers within a given event. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/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, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "seat": null, "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false } ] } :query integer page: The page number in case of a multi-page result set, default is 1 :query string code: Only show the voucher with the given voucher code. :query integer max_usages: Only show vouchers with the given maximal number of usages. :query integer redeemed: Only show vouchers with the given number of redemptions. Note that this doesn't tell you if the voucher can still be redeemed, as this also depends on ``max_usages``. See the ``active`` query parameter as well. :query boolean block_quota: If set to ``true`` or ``false``, only vouchers with this value in the field ``block_quota`` will be shown. :query boolean allow_ignore_quota: If set to ``true`` or ``false``, only vouchers with this value in the field ``allow_ignore_quota`` will be shown. :query string price_mode: If set, only vouchers with this value in the field ``price_mode`` will be shown (see above). :query string value: If set, only vouchers with this value in the field ``value`` will be shown. :query integer item: If set, only vouchers attached to the item with the given ID will be shown. :query integer variation: If set, only vouchers attached to the variation with the given ID will be shown. :query integer quota: If set, only vouchers attached to the quota with the given ID will be shown. :query string tag: If set, only vouchers with the given tag will be shown. :query integer subevent: Only return vouchers of the sub-event with the given ID :query string ordering: Manually set the ordering of results. Valid fields to be used are ``id``, ``code``, ``max_usages``, ``valid_until``, and ``value``. Default: ``id`` :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)/vouchers/(id)/ Returns information on one voucher, identified by its internal ID. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/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, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "seat": null, "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false } :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 voucher 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)/vouchers/ Create a new voucher. **Example request**: .. sourcecode:: http POST /api/v1/organizers/bigevents/events/sampleconf/vouchers/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json Content-Length: 408 { "code": "43K6LKM37FBVR2YG", "max_usages": 1, "valid_until": null, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false } **Example response**: .. sourcecode:: http HTTP/1.1 201 Created Vary: Accept Content-Type: application/json { "id": 1, "code": "43K6LKM37FBVR2YG", "max_usages": 1, "redeemed": 0, "valid_until": null, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "seat": null, "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false } :param organizer: The ``slug`` field of the organizer to create a voucher for :param event: The ``slug`` field of the event to create a voucher for :statuscode 201: no error :statuscode 400: The voucher 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. :statuscode 409: The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period. .. http:post:: /api/v1/organizers/(organizer)/events/(event)/vouchers/batch_create/ Creates multiple new vouchers atomically. **Example request**: .. sourcecode:: http POST /api/v1/organizers/bigevents/events/sampleconf/vouchers/batch_create/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json Content-Length: 408 [ { "code": "43K6LKM37FBVR2YG", "max_usages": 1, "valid_until": null, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false }, { "code": "ASDKLJCYXCASDASD", "max_usages": 1, "valid_until": null, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "12.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false }, **Example response**: .. sourcecode:: http HTTP/1.1 201 Created Vary: Accept Content-Type: application/json [ { "id": 1, "code": "43K6LKM37FBVR2YG", … }, … } :param organizer: The ``slug`` field of the organizer to create a vouchers for :param event: The ``slug`` field of the event to create a vouchers for :statuscode 201: no error :statuscode 400: The vouchers 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. :statuscode 409: The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period. .. http:patch:: /api/v1/organizers/(organizer)/events/(event)/vouchers/(id)/ Update a voucher. 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 ``redeemed`` fields. **Example request**: .. sourcecode:: http PATCH /api/v1/organizers/bigevents/events/sampleconf/vouchers/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json Content-Length: 408 { "price_mode": "set", "value": "24.00" } **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, "block_quota": false, "allow_ignore_quota": false, "price_mode": "set", "value": "24.00", "item": 1, "variation": null, "quota": null, "tag": "testvoucher", "comment": "", "seat": null, "subevent": null, "show_hidden_items": false, "all_addons_included": false, "all_bundles_included": false } :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 voucher to modify :statuscode 200: no error :statuscode 400: The voucher 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. :statuscode 409: The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period. .. http:delete:: /api/v1/organizers/(organizer)/events/(event)/vouchers/(id)/ Delete a voucher. Note that you cannot delete a voucher if it already has been redeemed. **Example request**: .. sourcecode:: http DELETE /api/v1/organizers/bigevents/events/sampleconf/vouchers/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 voucher 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.