To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
A single issued voucher, such as a gift card, discount code or entitlement, belonging to one voucher type. The voucher type holds the template, cash value and expiry rules, and this row is one instance of it identified by its voucherId. Its lifecycle is a single letter status code, see VOUCHER_STATUS_CODE, and every change to that code is copied to a VoucherStatusChange for auditing. A voucher may be allocated either to a Kademi profile or to an external identifier, may carry a cash value and an expiry date that override the ones on the type, and is linked to a Cart when it is redeemed through a checkout. Deletion is soft: a deleted voucher keeps its row and records who deleted it and when.
Group: Database Entities
Implements: Serializable, Relational
Properties
| Property | Returns | Description |
|---|---|---|
| allocatedTo | Profile | The Kademi profile currently holding this voucher, if it was allocated to a known user. Null when the voucher is unallocated or was allocated to an external recipient, in which case see getAllocatedToId. Cleared by a soft delete. Loaded lazily. |
| allocatedToId | String | External identifier of the recipient holding this voucher, for recipients who are not Kademi profiles. Null when the voucher is unallocated or is allocated to a profile. Cleared by a soft delete. |
| cancelled | boolean | Whether the voucher has been cancelled, meaning its status code is C. Cancelled vouchers can never be redeemed again. |
| cart | Cart | The shopping cart this voucher was applied to, set when it is redeemed through a checkout. Null for vouchers redeemed outside a checkout or not yet redeemed. Loaded lazily. |
| cashValue | BigDecimal | Cash value for this individual voucher, overriding the value on the voucher type. Null means use the type's value, so read getFinalCashValue rather than this when you want the amount actually in force. |
| createdBy | Profile | The profile that generated the voucher, normally the administrator who ran the voucher creation. Loaded lazily. |
| createdDate | Date | When the voucher was generated. This is not the date it was allocated or redeemed, which are tracked by the status date. |
| deletedBy | Profile | The profile that soft deleted this voucher. Non-null means the voucher is deleted and should be excluded from listings. Loaded lazily. |
| deletedDate | Date | When the voucher was soft deleted. The row is kept so the voucher code cannot be reissued and the audit trail survives. |
| expiryDate | Date | The date past which the voucher can no longer be redeemed. It is calculated from the voucher type's expiry rules when the voucher is allocated, is null when there is no expiry, and is cleared by a soft delete. |
| fields | NvSet | Custom name and value pairs captured against this voucher, matching the field set defined on the voucher type. Use the field method to read a single value safely. Loaded lazily. |
| finalCashValue | BigDecimal | The cash value actually in force for this voucher: the per voucher override if one is set, otherwise the value from the voucher type. This is the amount to use when applying the voucher to an order. |
| id | long | Database identifier for this voucher, assigned when the row is first saved. |
| redeemingOrg | Organisation | The organisation that may redeem this voucher, taken from the voucher type. This is usually different from the organisation that issued the type, and it is one of the two orgs that grant an administrator access to the voucher. |
| reqDay | int | Day of the month of the last status change, denormalised from the status date for reporting. Zero until the status is first set. |
| reqMonth | int | Calendar month of the last status change, denormalised from the status date for reporting. It is taken straight from java.util.Calendar, so it is zero based: January is 0 and December is 11. Zero also means the status has never been set, so test the status date if you need to tell those apart. |
| reqYear | int | Calendar year of the last status change, denormalised from the status date so reports can group by period without a date function. Zero until the status is first set. |
| status | String | The single letter lifecycle code: A allocated, I idle, R redeemed, P pending, C cancelled, E expired. Blank or null means the voucher has been generated but not yet put into any state, which is treated as not redeemable. |
| statusChangedBy | Profile | The operator who made the most recent status change, for example the staff member who processed the redemption. Loaded lazily. |
| statusChangedForOrg | Organisation | The branch or store the most recent status change was made on behalf of, which is what redemption reporting groups by. Loaded lazily. |
| statusDate | Date | When the status was last changed, so for a redeemed voucher this is the redemption date. |
| voucherId | String | The voucher code as the recipient sees it, generated from the type's voucher ID template. It is unique within the voucher type, not globally, so always look a voucher up by code and type together. |
| voucherStatusChanges | List<VoucherStatusChange> | The audit trail of status changes, one entry per change, each recording the new status, who made it, when, the client IP and any operator notes. Notes added without a status change also appear here. |
| voucherType | VoucherType | The voucher type this voucher was issued from, which holds the title, template, cash value, expiry rules and the owning and redeeming organisations. |
| voucherTypeTitle | String | Display title of the voucher type, as a convenience for listings and templates. This is the free text display label, not the type's portable name, so do not use it as an identifier. |
Methods
getId() · getVoucherType() · getVoucherId() · getVoucherStatusChanges() · getCreatedDate() · getCreatedBy() · getAllocatedTo() · getAllocatedToId() · getStatus() · getStatusDate() · getStatusChangedBy() · getStatusChangedForOrg() · getExpiryDate() · getReqYear() · getReqMonth() · getReqDay() · getFields() · getDeletedBy() · getDeletedDate() · getCart() · getCashValue() · isCancelled() · field(String s) · getFinalCashValue() · getVoucherTypeTitle() · getRedeemingOrg() · isAvailableForRedemption(Date now)
getId()
Returns: long
Database identifier for this voucher, assigned when the row is first saved.
getVoucherType()
Returns: VoucherType
The voucher type this voucher was issued from, which holds the title, template, cash value, expiry rules and the owning and redeeming organisations.
getVoucherId()
Returns: String
The voucher code as the recipient sees it, generated from the type's voucher ID template. It is unique within the voucher type, not globally, so always look a voucher up by code and type together.
getVoucherStatusChanges()
Returns: List<VoucherStatusChange>
The audit trail of status changes, one entry per change, each recording the new status, who made it, when, the client IP and any operator notes. Notes added without a status change also appear here.
getCreatedDate()
Returns: Date
When the voucher was generated. This is not the date it was allocated or redeemed, which are tracked by the status date.
getCreatedBy()
Returns: Profile
The profile that generated the voucher, normally the administrator who ran the voucher creation. Loaded lazily.
getAllocatedTo()
Returns: Profile
The Kademi profile currently holding this voucher, if it was allocated to a known user. Null when the voucher is unallocated or was allocated to an external recipient, in which case see getAllocatedToId. Cleared by a soft delete. Loaded lazily.
getAllocatedToId()
Returns: String
External identifier of the recipient holding this voucher, for recipients who are not Kademi profiles. Null when the voucher is unallocated or is allocated to a profile. Cleared by a soft delete.
getStatus()
Returns: String
The single letter lifecycle code: A allocated, I idle, R redeemed, P pending, C cancelled, E expired. Blank or null means the voucher has been generated but not yet put into any state, which is treated as not redeemable.
getStatusDate()
Returns: Date
When the status was last changed, so for a redeemed voucher this is the redemption date.
getStatusChangedBy()
Returns: Profile
The operator who made the most recent status change, for example the staff member who processed the redemption. Loaded lazily.
getStatusChangedForOrg()
Returns: Organisation
The branch or store the most recent status change was made on behalf of, which is what redemption reporting groups by. Loaded lazily.
getExpiryDate()
Returns: Date
The date past which the voucher can no longer be redeemed. It is calculated from the voucher type's expiry rules when the voucher is allocated, is null when there is no expiry, and is cleared by a soft delete.
getReqYear()
Returns: int
Calendar year of the last status change, denormalised from the status date so reports can group by period without a date function. Zero until the status is first set.
getReqMonth()
Returns: int
Calendar month of the last status change, denormalised from the status date for reporting. It is taken straight from java.util.Calendar, so it is zero based: January is 0 and December is 11. Zero also means the status has never been set, so test the status date if you need to tell those apart.
getReqDay()
Returns: int
Day of the month of the last status change, denormalised from the status date for reporting. Zero until the status is first set.
getFields()
Returns: NvSet
Custom name and value pairs captured against this voucher, matching the field set defined on the voucher type. Use the field method to read a single value safely. Loaded lazily.
getDeletedBy()
Returns: Profile
The profile that soft deleted this voucher. Non-null means the voucher is deleted and should be excluded from listings. Loaded lazily.
getDeletedDate()
Returns: Date
When the voucher was soft deleted. The row is kept so the voucher code cannot be reissued and the audit trail survives.
getCart()
Returns: Cart
The shopping cart this voucher was applied to, set when it is redeemed through a checkout. Null for vouchers redeemed outside a checkout or not yet redeemed. Loaded lazily.
getCashValue()
Returns: BigDecimal
Cash value for this individual voucher, overriding the value on the voucher type. Null means use the type's value, so read getFinalCashValue rather than this when you want the amount actually in force.
isCancelled()
Returns: boolean
Whether the voucher has been cancelled, meaning its status code is C. Cancelled vouchers can never be redeemed again.
field(String s)
Returns: String
Reads one custom field value by name, returning null rather than failing when the voucher has no field set at all or has no value for that name.
| Parameter | Description |
|---|---|
s | the field name, as defined in the voucher type's field set |
getFinalCashValue()
Returns: BigDecimal
The cash value actually in force for this voucher: the per voucher override if one is set, otherwise the value from the voucher type. This is the amount to use when applying the voucher to an order.
getVoucherTypeTitle()
Returns: String
Display title of the voucher type, as a convenience for listings and templates. This is the free text display label, not the type's portable name, so do not use it as an identifier.
getRedeemingOrg()
Returns: Organisation
The organisation that may redeem this voucher, taken from the voucher type. This is usually different from the organisation that issued the type, and it is one of the two orgs that grant an administrator access to the voucher.
isAvailableForRedemption(Date now)
Returns: boolean
Tests whether the voucher can be redeemed at the given moment. It must have a status, that status must not be cancelled, redeemed, idle, pending or expired, and its expiry date must not have passed, so in practice only an allocated voucher qualifies. Rejections are logged.
| Parameter | Description |
|---|---|
now | the date and time to test against, normally the current time |
© 2025 Kademi Ltd