Voucher

Properties

Our voucher entity has multiple properties you can control.

amount (numeric) _required

The numeric is the value, which defines the reduction of the amount to pay.

Example

44

If not provided...

{
    "message": "AMOUNT_REQUIRED",
    "error": "Bad Request",
    "statusCode": 400
}

type (VoucherType) _required

The type of the voucher defines if the amount is just an amount of money, that will be substracted or if it's a percentage value.

Value	Description
AMOUNT	The amount is (money) value.
PERCENTAGE	The amount is a percentage value.

Example

PERCENTAGE

If not provided...

{
    "message": "TYPE_REQUIRED",
    "error": "Bad Request",
    "statusCode": 400
}

name (string)

A voucher can have a name. The value will not be displayed when redeeming a voucher. You will retrieve this information via webhook payload.

Example

Et tu, Brute?

description (string)

A voucher can have a description. The value will not be displayed when redeeming a voucher. You will retrieve this information via webhook payload.

Example

Alea iacta est - A Latin proverb, but stolen from the Greek.

reference (string)

For analysis you can add a reference to a voucher to keep track of the status.

Example

Folio: 0815

code (string)

You can provide a code on your own. But you can also use the CodeGenerator

Example

MY-CODE-2024

validFrom (date)

You can create a voucher that will only become valid in the future.

Format

As defined in ISO 8601 use a date time format like YYYY-MM-DDThh:mm:ss.

Default

DateTime of creation.

Example

1987-12-23T11:54:00

validUntil (date)

You can create a voucher that will only become valid in the future.

Format

As defined in ISO 8601 use a date time format like YYYY-MM-DDThh:mm:ss.

Default

validFrom + 1 year

Example

1988-12-23T11:54:00

usage (VoucherUsage)

A voucher is assigned to a specific group of people, e.g. to carry out targeted marketing campaigns with a voucher.

Value	Description	Default
PUBLIC	The voucher code is available for everyone.
CUSTOMER	The voucher is for one specific customer.

Example

PUBLIC

quota (number)

A quota limits the generation of a voucher. If you created a voucher for a campaign you can limit how often the voucher could redeemed.

Explanation

• Let's asume, you're having a campaign for example "The first 100 will have a 5 %".
• The voucher code is FIRST100
• So if guest performs the checkout and enters FIRST100 as voucher code, the system will do the following:
  1. If there's a quota left, the amount will be reduced by 5 %.
  2. If there's no quota left, the guest will not have a reduction.

Example

100

default (boolean)

This voucher will be the blueprint for creating vouchers for usage.CUSTOMER if you want to invite guest to join your voucher program.

Default

false

deactivated (boolean)

Easily mark a voucher as not valid anymore.

Default

false

customerReference (json)

You can provide more details about the owner of the voucher - if you have.

Object definition

We recommend to use this structure, to serialize the data. Provide only fields you have.

{
    "email": "",
    "firstname": "",
    "lastname": "",
    "phone": ""
    "salutation": "Choose from `Mr`, `Mrs`"
}

thirdPartyPayload (json)

You can add own information to a generated voucher.

We will not process any of the information in this property

Object definition

It's up to you, what you want to add.

{
    "appRef": "",
    "customerId": "",
    "arragementId": "",
}

codeGeneratorSettings (VoucherCodeGeneratorSettings)

You can use a built in generator to let you create codes.

Definition

Defines how the code should look like, when automatically generated.

Property	Type	Description	Default
charset	enum	Defines, which chars sould be used. Can be numerical, alphanumerical, alphabetical.	numerical
length	number	Length of code	8
pattern	string	You can define a patter by using #. Each # will be replaced by a char of the genrator code. All other than # will count as one character as well.	####-###
prefix	string	Use this to add something before the code.	empty
suffix	string	Use this to add someting to the end.	empty
uppercase	boolean	If using alphabetical or alphanumerical all chars will be uppercase if true - otherwise it could be a mix of upper- and lowercase characters.	abc