Vouchers¶

Resource description¶

The voucher resource contains the following public fields:

Field	Type	Description
id	integer	Internal ID of the voucher
created	datetime	The creation date of the voucher. For vouchers created before pretix 2025.7.0, this is guessed retroactively and might not be accurate.
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.
budget	money (string)	The budget a voucher is allowed to consume before being used up (or `null`)
budget_used	money (string)	The amount of budget the voucher has already used up.

Changed in version 2025.7: The attributes created, budget, and budget_used have been added.

Endpoints¶

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

Returns a list of all vouchers within a given event.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/vouchers/ 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,
      "created": "2020-09-18T14:17:40.971519Z",
      "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,
      "budget": None,
      "budget_used": "0.00"
    }
  ]
}

Query Parameters:

page (integer) – The page number in case of a multi-page result set, default is 1
code (string) – Only show the voucher with the given voucher code.
max_usages (integer) – Only show vouchers with the given maximal number of usages.
redeemed (integer) – 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.
block_quota (boolean) – If set to true or false, only vouchers with this value in the field block_quota will be shown.
allow_ignore_quota (boolean) – If set to true or false, only vouchers with this value in the field allow_ignore_quota will be shown.
price_mode (string) – If set, only vouchers with this value in the field price_mode will be shown (see above).
value (string) – If set, only vouchers with this value in the field value will be shown.
item (integer) – If set, only vouchers attached to the item with the given ID will be shown.
variation (integer) – If set, only vouchers attached to the variation with the given ID will be shown.
quota (integer) – If set, only vouchers attached to the quota with the given ID will be shown.
tag (string) – If set, only vouchers with the given tag will be shown.
subevent (integer) – Only return vouchers of the sub-event with the given ID
ordering (string) – Manually set the ordering of results. Valid fields to be used are id, code, max_usages, valid_until, and value. Default: id

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)/vouchers/(id)/¶

Returns information on one voucher, identified by its internal ID.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/vouchers/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,
  "created": "2020-09-18T14:17:40.971519Z",
  "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,
  "budget": None,
  "budget_used": "0.00"
}

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 voucher 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)/vouchers/¶

Create a new voucher.

Example request:

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:

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

{
  "id": 1,
  "created": "2020-09-18T14:17:40.971519Z",
  "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,
  "budget": None,
  "budget_used": "0.00"
}

Parameters:

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

Status Codes:

201 Created – no error
400 Bad Request – The voucher 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.
409 Conflict – The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period.

POST /api/v1/organizers/(organizer)/events/(event)/vouchers/batch_create/¶

Creates multiple new vouchers atomically.

Example request:

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:

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

[
  {
    "id": 1,
    "created": "2020-09-18T14:17:40.971519Z",
    "code": "43K6LKM37FBVR2YG",
    …
  }, …
}

Parameters:

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

Status Codes:

201 Created – no error
400 Bad Request – The vouchers 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.
409 Conflict – The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period.

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:

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:

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

{
  "id": 1,
  "created": "2020-09-18T14:17:40.971519Z",
  "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,
  "budget": None,
  "budget_used": "0.00"
}

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

Status Codes:

200 OK – no error
400 Bad Request – The voucher 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.
409 Conflict – The server was unable to acquire a lock and could not process your request. You can try again after a short waiting period.

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:

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