Powered by Redocly

Vouchers

Manage ticket vouchers.

Voucher

A voucher provides an additional discount on a ticket and includes the following features and constraints: Usage Limits - Each voucher can be used up to 1000 times (see v2/tickets/voucher-items for insights into the amount of usages per voucher). - It can be redeemed by either a customer or an operator. Validity Period - A voucher is only valid between its valid_from and valid_until dates (inclusive). - It can be deactivated at any time to prevent usage during its validity period. Optional Restrictions - A voucher can be restricted to:

  • A specific customer.
  • Tickets that include a specific product.

Voucher Types There are two types of vouchers:

  1. Unique Code Vouchers

    • Contain a set of individual, unique codes.
    • Ideal for direct distribution (e.g., via email or printed materials) or for one-time use (e.g. for a rectification or compensation).

  2. Generic Code Vouchers

    • Use a single shared code.
    • Best suited for marketing campaigns and broader distribution.
id
string <uuid>

Identifier of the voucher.

label
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

currency
string <iso-4217>

The currency of the monetary amount.

valid_from
string <date>

Date when the voucher becomes valid.

valid_until
string <date>

Date after which the voucher becomes invalid.

is_active
boolean
Default: true

Indicates if the voucher is active.

customer_id
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": 5,
  • "discount_money": {
    },
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}

VoucherItem

A voucher item represents a single redeemable code of a voucher. Voucher items can be enabled or disabled, and can be used on a ticket to receive additional discount.

code
string

Voucher item code. This is the code that can be used to redeem this voucher item.

voucher_id
string <uuid>

Identifier of the voucher.

enabled
boolean

Whether this voucher item is enabled and can be used. A used item cannot be disabled.

customer_id
string or null <uuid>

Identifier of customer that can or has used this voucher item.

ticket_id
string or null <uuid>

Identifier of ticket on which this voucher item has been used.

used_at
string or null <date-time>

Date and time when this voucher item has been used.

{
  • "code": "string",
  • "voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b",
  • "enabled": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "ticket_id": "595be628-f6f2-4262-9c10-6389c6c4a5b8",
  • "used_at": "2019-08-24T14:15:22Z"
}

Retrieve vouchers

Retrieve a list of vouchers.

SecurityOAuth2
Request
query Parameters
availability
boolean
Default: true

Filter vouchers by their availability. When true only returns vouchers with at least 1 unused item. Vouchers with only used items when false.

code
string [ 6 .. 20 ] characters

Filter voucher by code. Only returns voucher of which the generic_code or the code of one of its items matches.

customer_id
string <uuid>

Filter vouchers by customer identifier. Returns vouchers that have on or more items bound to provided customer.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

Limits the amount of resources in result.

offset
integer <int64> >= 0
Default: 0

Offset of resources in result.

object

Filter vouchers by the date they become valid.

object

Filter vouchers by the date until they are valid.

Responses
200

Successful response.

Response Schema: application/json
object >= 0 properties

Applied query parameters, including defaults.

availability
boolean
Default: true

The applied value of the availability query parameter on the resources in result.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

The applied value of the limit query parameter on the resources in result.

offset
integer <int64> >= 0
Default: 0

The applied value of the offset query parameter on the resources in result.

property name*
additional property
any
Array of objects (Voucher) >= 0 items

List of vouchers.

Array (>= 0 items)
id
string <uuid>

Identifier of the voucher.

label
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

valid_from
string <date>

Date when the voucher becomes valid.

valid_until
string <date>

Date after which the voucher becomes invalid.

is_active
boolean
Default: true

Indicates if the voucher is active.

customer_id
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

total
integer <int64>

Total number of resources matching provided query parameters.

default

An error occurred - see status code and problem response for more information.

get/v2/tickets/vouchers
Response samples
application/json
{
  • "query": {
    },
  • "result": [
    ],
  • "total": 4
}

Add a voucher

Add a new voucher.

SecurityOAuth2
Request
Request Body schema: application/json

The voucher you wish to add.

label
required
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
required
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
required
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

required
object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

valid_from
required
string <date>

Date when the voucher becomes valid.

valid_until
required
string <date>

Date after which the voucher becomes invalid.

customer_id
required
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
required
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

Responses
201

Created.

Response Schema: application/json
id
string <uuid>

Identifier of the voucher.

label
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

currency
string <iso-4217>

The currency of the monetary amount.

valid_from
string <date>

Date when the voucher becomes valid.

valid_until
string <date>

Date after which the voucher becomes invalid.

is_active
boolean
Default: true

Indicates if the voucher is active.

customer_id
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

400

Bad request.

default

An error occurred - see status code and problem response for more information.

post/v2/tickets/vouchers
Request samples
application/json
{
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": null,
  • "discount_money": null,
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": 5,
  • "discount_money": {
    },
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}

Retrieve a voucher

Retrieves a voucher by its identifier.

SecurityOAuth2
Request
path Parameters
voucher-id
required
string <uuid>

The identifier of the voucher.

Responses
200

Successful response.

Response Schema: application/json
id
string <uuid>

Identifier of the voucher.

label
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

currency
string <iso-4217>

The currency of the monetary amount.

valid_from
string <date>

Date when the voucher becomes valid.

valid_until
string <date>

Date after which the voucher becomes invalid.

is_active
boolean
Default: true

Indicates if the voucher is active.

customer_id
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

default

An error occurred - see status code and problem response for more information.

get/v2/tickets/vouchers/{voucher-id}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": 5,
  • "discount_money": {
    },
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}

Update a voucher

Update a voucher by its identifier.

SecurityOAuth2
Request
path Parameters
voucher-id
required
string <uuid>

The identifier of the voucher.

Request Body schema: application/json
required

The updated voucher.

label
required
string [ 2 .. 255 ] characters

Label of the voucher.

discount_percentage
required
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

required
object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

valid_from
required
string <date>

Date when the voucher becomes valid.

valid_until
required
string <date>

Date after which the voucher becomes invalid.

is_active
required
boolean
Default: true

Indicates if the voucher is active.

Responses
200

Successful response.

Response Schema: application/json
id
string <uuid>

Identifier of the voucher.

label
string [ 2 .. 255 ] characters

Label of the voucher.

generic_code
string or null [ 6 .. 20 ] characters ^[A-Z0-9-]+$

The generic code that can be used to receive the additional discount. If null the discount can be received by using the unique code of an item.

discount_percentage
number or null <number> [ 0 .. 100 ]
Default: 0

The discount percentage received when a code from this voucher is used on a ticket. A value of 20 represents a discount of "20%". Value is null if discount_money is not null.

object or null (Money)

The discount money received when a code from this voucher is used on a ticket. Value is null if discount_percentage is not null.

amount
required
number <float> >= 0

The monetary amount.

currency
string <iso-4217>

The currency of the monetary amount.

valid_from
string <date>

Date when the voucher becomes valid.

valid_until
string <date>

Date after which the voucher becomes invalid.

is_active
boolean
Default: true

Indicates if the voucher is active.

customer_id
string or null <uuid>

Identifier of the customer this voucher is applicable to. If null the voucher is applicable to all customers.

product_ids
Array of strings <uuid> >= 0 items

List of product identifiers this voucher is applicable to. If empty the voucher is applicable to all products.

default

An error occurred - see status code and problem response for more information.

put/v2/tickets/vouchers/{voucher-id}
Request samples
application/json
{
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": null,
  • "discount_money": null,
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "label": "Summer 2025",
  • "generic_code": "SUMMER-2025",
  • "discount_percentage": 5,
  • "discount_money": {
    },
  • "valid_from": "2025-08-01",
  • "valid_until": "2025-12-31",
  • "is_active": true,
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "product_ids": [
    ]
}

Add voucher item generation request

Add voucher item generation request.

SecurityOAuth2
Request
Request Body schema: application/json

The voucher item generation request you wish to add.

num_items
integer <int32> [ 1 .. 1000 ]

The number of voucher items to generate.

voucher_id
required
string <uuid>

The identifier of the voucher to generate items for..

Responses
201

Created.

Response Schema: application/json
num_items
integer <int32>

The number of voucher items generated.

voucher_id
string <uuid>

The identifier of the voucher the items were generated for.

400

Bad request.

default

An error occurred - see status code and problem response for more information.

post/v2/tickets/voucher-item-generation-requests
Request samples
application/json
{
  • "num_items": 1,
  • "voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b"
}
Response samples
application/json
{
  • "num_items": 0,
  • "voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b"
}

Retrieve voucher items

Retrieve a list of voucher items.

SecurityOAuth2
Request
query Parameters
code
string [ 6 .. 20 ] characters

Filter voucher items by code. Only returns voucher item of which the code matches.

customer_id
string <uuid>

Filter voucher items by the identifier of the customer that can or has used it. Combine with used to filter by usage status.

is_enabled
boolean
Default: true

Filter voucher items by enabled status.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

Limits the amount of resources in result.

offset
integer <int64> >= 0
Default: 0

Offset of resources in result.

ticket_id
string <uuid>

Filter voucher items by the identifier of the ticket it was used on.

used
boolean
Default: true

Filter voucher items by usage status.

object

Filter voucher items that were used on, before or after provided date.

voucher_id
string <uuid>

Filter voucher items by the identifier its voucher.

Responses
200

Successful response.

Response Schema: application/json
object >= 0 properties

Applied query parameters, including defaults.

is_enabled
boolean
Default: true

The applied value of the is_enabled query parameter on the resources in result.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

The applied value of the limit query parameter on the resources in result.

offset
integer <int64> >= 0
Default: 0

The applied value of the offset query parameter on the resources in result.

used
boolean
Default: true

The applied value of the used query parameter on the resources in result.

property name*
additional property
any
Array of objects (VoucherItem) >= 0 items

List of voucher items.

Array (>= 0 items)
code
string

Voucher item code. This is the code that can be used to redeem this voucher item.

voucher_id
string <uuid>

Identifier of the voucher.

enabled
boolean

Whether this voucher item is enabled and can be used. A used item cannot be disabled.

customer_id
string or null <uuid>

Identifier of customer that can or has used this voucher item.

ticket_id
string or null <uuid>

Identifier of ticket on which this voucher item has been used.

used_at
string or null <date-time>

Date and time when this voucher item has been used.

total
integer <int64>

Total number of resources matching provided query parameters.

default

An error occurred - see status code and problem response for more information.

get/v2/tickets/voucher-items
Response samples
application/json
{
  • "query": {
    },
  • "result": [
    ],
  • "total": 4
}
➔ Next to Messenger channel messages